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Visual Development Environment For 


WATGOM VX°RExx is an easy to use visual development 
environment for creating applications that leverage the 
capabilities of OS/2 2.x and exploit the Presentation Manager 
graphical user interface. VX*REXX combines a project 
management facility, visual designer and an interactive source- 
level debugger to deliver a very approachable and highly 
productive visual development environment. 





Powerful Open 
Environment Enjoy the 
simplicity of event-driven 
programming together with the 
global editing capabilities 
essential for professional project 
management. WATCOM 
VX*REXX is open and extensible 
through IBM’s object oriented 
System Object Model (SOM) 


Design Applications 
Visually Create rich graphical 
applications quickly and easily using 
the visual design environment. With 


Integrated Development 
Environment Build, test and 
debug your application without 
leaving the development 


technology. You can access all 
standard REXx API’s including 
DB Manager, because V X*REXX 
is based on the OS/2 2.x standard 


environment. Then package your 
application as an EXE file or PM 
macro for royalty-free redistribution. 
The power of the integrated 
development environment and 
debugger can also be used with your 
existing REXx applications. 


the visual designer, you can 
graphically create Presentation 
Manager interface objects, quickly 
customize their properties, and 
easily attach REXx procedures to 
the objects. 


system REXX. 





























Highlights 


> Easy to use visual development environment > Support for multi-threaded applications 


» Create and modify objects dynamically at > Include 0S/2 style help and hints in your 
both edit and run time applications 


> Powerful project management facility > Supports SAA CUA’91 objects 
>» Advanced interactive source-level debugger > Autosizing and alignment of objects 
» Package your applications as EXE files or > Integrated console window support for 
PM macros existing Rexx programs 
» Access to standard Rexx API's including > Royalty-free run-time available 
DB Manager > | 
. Multiple modeless window support 
> System Object Model (SOM) based object > Rasats PM macros for cpplletions 


manager supporting Rexx as a macro language 





Interactive 0 

[f an error occurs at run- -time, 
VX*REXX will display a traceback 
pinpointing the source line where 
the error occurred. A simple click 
of the mouse will return you to the 
source edit window to correct the 
error. The built-in interactive 
source-level debugger lets you set 
breakpoints, step through code 
and watch variables to track down 
complex problems. 
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Applications 

WATCOM VX*REXX allows 

you to leverage key OS/2 features 
to create professional applications. 








4 . 1 2 : F 5 
Build applications that dynamically mon VE an | 
create and modify CUA’91 screen \ 0008, (ct ee 
objects at both edit and run-time, \ 19000 
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and include OS/2 style help and hints. “\e 


rine lic catio ns S : Every VX*REXX 
application contains multiple threads. 

One thread remains responsive to user 
input while others continue processing. 
In addition, VX*REXx provides the 
ability for advanced applications to easily 
use additional threads. 
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WATCEOM VX-RExx: 
The integrated visual 
solution builder for OS/2 2.x. 








WATCOM International 
415 Phillip Street, Waterloo, Ontario, Canada, N2L 3X2 
Phone: (519) 886-3700 Fax: (519) 747-4971 


*Prices and specification are subject to change without notice. Price does not include freight and taxes where applicable. Prices 
quoted in US dollars. WATCOM, the Lightning Device, and VX*Rexx are trademarks of WATCOM International Corporation. Other 
trademarks are the properties of their respective owners. © Copyright 1993 WATCOM International Corporation. 


» We were told it was impossib 
to develop a client/server application 
without extensive retraining 
Then we talked to Micro Focus ® 


a 


Larry Lowder, Systems Architect, Qmestar Service Corporation. 


Mountain Fuel Supply® a division of Questar® is a utility company 
supplying natural gas to 750,000 customers across Utah, Wyoming, Idaho 
and Colorado. The company’s success is largely driven by its implicit belief 
that the customer is number one. 

Yet, IT also plays its part in that success: client/server architectures and 
graphical user interfaces (GUIs) have helped Mountain Fuel Supply move 
applications and information closer to the customers and the employees. All 
of which has resulted in an augmented level of service being offered to 
customers. 

When Larry Lowder, one of Questar’s Systems Architects, set out to 
build the client/server architecture for Mountain Fuel Supply, he needed 
solutions, not skepticism. For the first project, a cashiering system, he 
needed to link workstations with 05/2" to the DB2*® database on the host, 
running CICS* 


“We were faced with having to spend up to two years retraining our 





COBOL programmers in C and API calls. Then we discovered Micro Focus 
Dialog System™ It allowed us to build the client functionality we required, 
and re-engineer the existing mainframe application as a server.” 

“Within a week, mainframe programmers were producing GUI screens 
for COBOL. Within 90 days we had delivered the system. Now we're not 
only coming in under budget, but also way ahead of schedule.” 

As Mountain Fuel Supply discovered, the Micro Focus solution lets 
you make a productive transition to client/server without sacrificing any of 
the resources you've worked so hard to build. 

When the world’s leading corporations demand “A Better Way of 


Tel #7 


Programming;” they turn to Micro Focus. For a brochure on putting the 


Micro Focus Client/Server Solution to work for you, call 800-872-6265. 


Micro Focus Inc. 2465 East Bayshore Road, Palo Alto, CA 94303. Tel. (415) 856 4161. 


Micro Focus isa registered trademark and Dialog System and “A Better Way of Programming” are trademarks of Micro Focus, Inc. All other trademarks are property of their respective companies 


GSA Contract Number GSOOK93AGS$6403. 
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IBM® OS/2° 2.1 
by IBM Corporation 


05/2's pre-emptive, multithreaded multitask- 
ing allows you to run multiple tools concurrent- 
ly. This means you can edit in one session 
while a compile-and-link occurs in another, 
and a print job occurs in a third. By operating 
pre-emptively, OS/2 makes sure all running 
applications get the time they need to run, so 
that overall performance is improved. 


List: $249 Ours: $139 
Upgrade List: $199 Ours: $ 99 
FAXcetera #: 3142-0009 


for OS/2 featuring numerous animated 








BocaSoft Wipeout & 
BocaSoft System 

by BocaSoft Inc. 

BocaSoft WipeOut is a 32-bit screen saver 





displays integrated with digital audio, 
password protection, screen capture, randomizer, and on-line help, A 
developer kit is included that allows the development of new screen savers. 


zs = 3 is a 32-bit OS/2 application that allows the asso- 
coneieas ol i spstiai events, keystrokes and mouse events with digital audio. 


WipeOut List: $59 Ours: $55 
System Sounds List: $59 Ours: $55 
FAXcetera #: 1010-2501 








WATCOM VX¢RExx 
by WATCOM Int'l Corp. 


WATCOM VX*REXX is an easy to use visual 
development environment for creating applica- 
tions that leverage the capabilities of OS/2 2.x 
and exploit the Presentation Manager graphical 
user interface. VX*REXX combines a _ project 
Management facility. visual designer and an 
inieractive source-level debugger to deliver a very approachable and highly 
productive visual development environment. 

List: $299 Ours: $99 


Introductory Offer! (until Sept. 30, 1993) 
FAXcetera #: 1683-0016 


WATOOM 





SQL Objects++™ 
Database Class Library 
by Graphical Software 
Interfaces, Inc. Objects 2 ai 
SQL Objects++™ Database Class Library | Database Class Li brary| 
is a powerful collection of object-oriented = . 

database classes that provide direct access to SQL and non-SQL databas- 
es. Each class is fully optimized to provide fast access to your data. No 
other access library is designed to fully utilize your OS/2 environment. 


List: $499 Ours: $249 


Introductory Offer! (until Oct. 31,1993) 
FAX cetera #: 1010-2601 








Greenleaf Comm++ v2.0 
by Greenleaf Software, Inc. Greendeal 


Comrune+ 


Comm++ will accommodate interrupt-driven 
circular buffered service for 35 ports at baud 
rates to 115,200. As a C++ communications 
library, it provides a hierarchy of classes 
which give the programmer simple access 
and contro! of serial communications. 
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Classes are provided for: serial port controls, modem controls, file transfer 


protocols and calculation of check values. 


List: $249 Ours: $199 
FAX cetera #: 1035-0011 


C++/Views for OS/2 


by Liant Software 
Corporation 


Use C++/Views to help you quickly create 
high-quality 32-bit GUI applications for OS/2 
2.x! What's more, applications developed with 
C++/Views are fully source-code portable to 
the other major operating environments—MS 
Windows, Motif, and Macintosh, C++/Views 
achieves this portability without sacrificing 
features, performance, or a native look and feel. 


List: $999 Ours: Call for special pricing 
FAXcetera #: 1952-0021 








Error Manager™ £2.08 Sotare Deveoomat To 
by Soft & GUI, Inc. | 


Introducing Error Manager (EM), the runtime API _ Error > 
debugger and production code monitor. EM finds | Manag er 
elusive API errors and enables Testers and | 

Production Managers to monitor software in real |" 
user environments. Best of all, EM works with 
fully optimized code and does not require symbol 
information or the Debug Kernel—yet it will tell 
you which line in your source is causing the error! 


List: $225 Ours: $169 
FAX cetera #: 1002-0301 





h= we 


rn —— rater 


}e Soft. & GUI. 
— 2 724 Enel Dist Sheet 
Brodin. AMY | dace 





GUARANTEED BEST PRICES! 
(Call for details) 


To order call: 800-445-7899 
Corporate (CORSOFT): 800 422-6507 
FAX: 908 389-9227 

International: 908 389-9228 
Customer Service: 908 389-9229 

For more information on the products 
featured on these pages call— 

FAXcetera®: (201) 762-1975 


1163 Shrewsbury Avenue 
Shrewsbury, NJ 07702 
* All prices are subject to change without notice. 
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BY DICK CONKLIN — 


his magazine is now beginning its sixth 
year of publication—as always, propelled 
by change. If you can pardon a bit of nos- 
talgia, I'd like to bring you—especially our newer 
readers—up to date on where we've been and 
where we're going. 





Communicate! IBM Personal Systems Developer was 


| launched in 1988, following a survey of indepen- 


dent software vendors enrolled in IBM's Develop- 
er Assistance Program. DAP members had asked 
IBM to improve its communications with them; a 
“newsletter” was suggested. I had just written 
OS/2: A Business Perspective and saw the need for a 


| regular OS/2 publication. The newsletter became 
a magazine, and the first issue (a skinny 48 pages) 


just barely made COMDEX Fall ‘88, where we 
handed out 25,000 copies. 


Big Blue, Too. Although our target audience was 
software vendors, we soon noticed an increase in 
subscribers from IBM's traditional customer base. 
Corporate in-house programming departments 


were also adopting OS/2 and shared the need for 


current technical advice. Both groups want to 


optimize performance, exploit the Workplace 


Shell, write bug-free code, and move into the 
world of objects. 


Ready for Prime Time. Last year we changed pub- 
lishers, selecting Miller Freeman Inc., a San Fran- 
cisco-based company with impressive credentials. 
MFI, which also publishes Software Development, 
Dr. Dobbs Journal, and Microsoft Systems Journal, 
knows the trade magazine business well and 
helped the renamed OS/2 Developer enter the retail 
market, find new subscribers, and start publish- 
ing bimonthly. Today we are an independent 

















—— _-altors 
Comments 


Two Paths Converge 


OS/2 publication designed to serve commercial 
and corporate OS/2 developers worldwide. 


Five Years Old and Counting. As we 
enter our second half-decade, it 
seems appropriate to remember some 
of the people who got us here: Bob 
Tabke and Debbie Dawson of the 
TDA Group, Jo-Ann Campbell of | 7 
MLE Design, IBM’s Lee Reiswig and gl 
former IBMers Don Barovich, Brian 
Proffit, and Mike Engelberg. And of 
course the pros at MFI: Don Pazour, 
Regina Ridley, Cathy Passage, Nicole Freeman, 
Lisa Gluskin, and everyone in advertising, circula- 
tion, and production. 





Dick Conklin 





This magazine was started because OS/2 devel- 
opers asked for it. We'll continue to pursue the kind 
of articles that will help you develop leading-edge 
OS/2 applications. To do that, we need to hear 
from you. Keep those cards and letters coming— 
via CompuServe, Internet, fax, or mail. 


Dh Cobo 


Dick Conklin, Editor 


Subscription information: U.5,: One year (six issues), $39.95. Canada, Mexico, and international surface mail, add $16 per year for postage. Canadian GST no. 124513185. Inter- 
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hile many software companies today 
praise the virtues of object-oriented 
programming (OOP) and graphical 


user interfaces (GUI), few can match the pedigree 
of Digitalk. The Los Angeles-based firm employs 
over 100 people in the design and development of 
software tools for OS/2 and other platforms. Its 
flagship product, Smalltalk/V, was an early offer- 
ing on the original IBM PC, later became a pio- 
neering OS/2 tool, and was recently upgraded to a 
full 32-bit application language. 

Today Digitalk’s OS/2 product line includes 
the OS/2 2.1-exploiting Smalltalk/V for OS/2, the 
Parts Assembly and Reuse Tool Set (PARTS) appli- 
cation development workbench, and the Team/V 
group development environment. 


‘All original Smalltalk development 
takes place on OS/2.” 
—dJim Anderson, CEO, Digitalk 


A SPARK FROM THE PARC 

Like so many software pioneers, Digitalk was 
influenced by work at Xerox’s Palo Alto Research 
Genter (PARC) in the early 1970s. PARC’s version 
of Smalltalk/V required mainframe performance 
and storage, but the desktop revolution of the 
1980s abolished that restriction. 





Digitalk, a Los Angeles-based maker of software tools, has revised and improved its Smalltalk product until it 
has become a full 32-bit application language. The company continues to push the frontiers of objects and 
object-oriented programming, as DICK CONKLIN discovers. 


Spotlight on Digitalk: Objects 
Pioneer Pushes the Envelope 


Jim Anderson is chairman and CEO of Digitalk 
and one of the company’s founders. His vision for 
the company originated 10 years ago while he and 
some colleagues were working on an overseas 
assignment. He remembers 1983 as a time of major 
change in the U. S. computer industry: “We were 
working in Italy for Com- 
puter Sciences Corporation 
on a new operating system, 
a COBOL compiler, and 
tools for an Olivetti banking 
mini-computer. As we 
approached the end of the 
project, the IBM PC had 
been launched and was tak- 
ing off like gangbusters. We 
got interested in PCs and 
the whole issue of personal Jim Anderson 
productivity. 

“We read the August 1981 issue of Byte Maga- 
zine, which was devoted to Smalltalk. At that time 
much of the work had taken place at Xerox PARC. 
To us, this language seemed ideal for developers 
to write PC applications; we convinced Olivetti to 
let us create a Smalltalk compiler for their banking 
system. We wrote it in Pascal.” 

In 1983, at the end of the project, Anderson 
formed Digitalk to put Smalltalk on the IBM PC. 
Digitalk shipped the first release in January 1985. 
Notes Anderson, “It was a complete Smalltalk 
development environment, DOS-based, floppy disk- 
based, called Methods. Some of the code from that 
product is still in Smalltalk/V today.” 


“~ 





OS/2 DEVELOPER 


Multiple Platforms, Multiple Skills. Anderson led 
Digitalk from its DOS origins to OS/2, Windows, 
and the Macintosh. All Smalltalk development 
at Digitalk first takes place on OS/2; the compa- 
ny introduces new products on it and then 
migrates to other platforms. “There’s even good 
portability,” says Anderson, “from OS/2 to the 
Mac.” 

Digitalk’s current product lines consist of 
Smalltalk/V, an object-oriented development envi- 
ronment, PARTS, a higher- 
level tool set for assembling 
objects and components, 
and Team/V, a _ group 
development and version 
control tool. Team/V now 
supports Smalltalk/V and 
in its August ‘93 release will 
support the PARTS product 
line. 


Anderson claims both 
software vendors and cor- 
porate developers among 
Digitalk’s customers, as well as users at various skill 
levels. “Smalltalk, as a language, takes more skill to 
use than PARTS, a higher-level tool,” he explains. 
“PARTS lets people create applications with a lower 
skill level—assembling elemental components that 
might be created in Smalltalk, COBOL, C, or other 
languages.” 


Lee Breisacher 


Object Oriented Management. Digitalk itself is in 
many ways a reflection of its software philosophy. 
“We have small teams for each product”, says 
Anderson. “There’s a strong parallel between 
object-oriented programming and the change in 
development organizations. It’s hard to build a 
software system that’s hierarchical, with some- 
one on the top giving orders to the rest of the 
program on what to do. 

“Objects,” he continues, “are decentralized 
software. Each object is an expert on its role but 
can utilize any other object to carry out what it 
wants to do.... It doesn’t need to go through a 
chain of command to get to other objects. Our 
organization is just like that. There are good rea- 
sons why objects work and why human organi- 
zations work the same way; both are very effi- 
cient.” 
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SMALLTALK: THE ORIGINAL 

OBJECT LANGUAGE 

Digitalk’s Smalltalk/V, the first commercial object- 
oriented language, today has over 125,000 licensed 
users. Its most dramatic change was made recent- 
ly, not to the language itself but to its runtime 
environment. The 32-bit version produces appli- 
cations that are up to twice as fast and half the size 
of their 16-bit counterparts. 


Smalltalk vs. C++. Lee Breisacher, a senior software 
engineer at Digitalk, is project manager of 
Smalltalk/V for OS/2. He has been developing 
Smalltalk/V products for five years and is an 
ardent evangelist for the language. “I think that 
someone who tries C++ for a few days and then 
tries Smalltalk/V will choose Smalltalk/V. Go on 
CompuServe and read the comments from people 
who are usingSmalltalk/V. OS/2 is a very rich 
operating system with hundreds and hundreds of 
APIs; you need to learn how they fit together and 
the arguments of each API. When I was using C++ 
I had to spend a few minutes re-learning each API 
each time I used it. Smalltalk/V protects you from 
all of that.” 

Mike Arrigo, Digitalk’s vice president of mar- 
keting, notes, “There is a style of programming 
with Smalltalk/V that just isn’t possible with C++. 
Because Smalltalk/V has an 
incremental compiler, you 
can see the results of your 
changes immediately; pro- 
grammers are more apt to 
try things, to see the results 
of what they have done to 
the code.” In contrast, in the 
C++ programming world, 
developers must do a re- 
compile and run a program 
before seeing where it 
breaks. “That alone makes Smalltalk programming 
a lot more productive,” explains Arrigo. 

Arrigo described the corporate world of the 90s 
as one still strongly influenced by COBOL: “C++ is 
still a software vendor development tool. It’s much 
easier for COBOL-trained people to learn 
Smalltalk and then devote their time to learning 
objects. The syntax is really simple, so you can get 
into objects right away.” 





Mike Arrigo 
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Figure 1. Smailltalk/V debugger 


According to Breisacher, the origi- 
nal DOS Smalltalk/V was an interpre- 
tive language, and current releases still 
retain that “feel,” even though they are 
compiled: “As fast as you can write a 
line of code you can test it. When you 
save your code, it is immediately com- 
piled and stored in 32-bit 80386 binary 


“Objects are decentralized 
software... Our organi- 
zation Is just like that.“ 


—Jim Anderson 


code, ready to run. You spend all your 
time—editing, running, debugging—in 
Small-talk/V.... You can even edit 
your code from the debugger.” (The 
Smalltalk/V debugger is shown in 
Figure 1.) 


Who Uses Smalltalk/V? Jim Anderson 
describes many of Digitalk’s customers 
as corporate shops using Smalltalk/V 


a 


r. Smalltalk/V {User VF} index: 8 is outside of collection bounds oO | 
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to “build the client side of client/server 
applications.” He says that customers 
use the language for “mission-critical 
applications,” citing as an example one 
customer service system for a large util- 
ity consortium that serves two million 
customers.” 

Barbara Noparstak, director of cor- 
porate communications at Digitalk, 
says that the company’s customers 
“continue to amaze us.” The U.S. Postal 
Service has programmed its new Postal 
Buddy stations, to be put in 60,000 post 
offices, in Smalltalk/V. Explains 
Noparstak, “They were one of our first 
large customers to use our OS/2 32-bit 
version. We shipped our product in 
September ‘92 and in January ‘93 they 
started deploying test systems to some 
pilot sites.” 

Smalltalk/V also works as a multi- 
platform application tool for indepen- 
dent software vendors. Some .DLL files 
are distributed with the application as 
part of Smalltalk/V’s runtime environ- 
ment, but Digitalk charges no royalty 
for their use. 

Says Breisacher, “We've spent a lot 
of time designing Smalltalk/V so it 
takes advantage of the environment in 


which it’s running. When you are run- 
ning under Windows, it looks like a 
Windows application, On OS/2 the 
screens appear the way you expect 
OS/2 screens to look. Same for the 
Mac.” The company’s next release, he 
adds, will make it easier to exchange 
code among the three platforms. 

Noparstak notes that Smalltalk/V is 
gaining a following among software 
vendors: “They find Smalltalk easier. 
Intersolv, for example, tried C++ but 
ran into too many problems. It was too 
complex and they weren't using objects 
properly. So they went to Smalltalk/V 
and got the job done in less time.” Ven- 
dors are also attracted by the fact that 
they don’t have to pay royalties for 
applications built with Smalltalk/V or 
PARTS. 


Exploiting 0S/2 2.X. Breisacher describes 
the upcoming version of Smalltalk/V 
for OS/2 2.x as having “true OS/2 
thread support and exception handling. 
You don’t have to use C code anymore 
to do those things. You can read from a 
named pipe and that thread will wait 
for something to come in. There’s also a 
new feature called Call-In; you’ll be 
able to write Smalltalk/V .DLLs as in 
any other lan- 
guage and call 
them as sub- 
routines from a 
C++ program.” 
Breisacher 
also gives some 
hints for the 
future: “We're 
working with 
IBM people in 
Austin on SOM 
support, which 
will ship later this year. Someday,” he 
promises, “you'll even be able to write 
SOM objects in Smalltalk/V.” 





Barbara Noparstak 


PARTS: DIGITALK’S HIGH-LEVEL 
APPLICATION TOOLSET 

PARTS is getting a lot of attention— 
and resources—at Digitalk these days. 
Jim Anderson likes to describe the 
PARTS Workbench, the framework for 
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the PARTS product line, as a tool that [iy 
“provides ease-of-use for programmers 
the way a GUI provides it for the user. 
Just as the notion ‘If I’ve seen one [ff /Player Pian 
application, I’ve seen them all’—same_ | Fil 
file menu, same edit menu, same drag- 
and-drop—works for users, we want to 
do the same for developers. We want 
‘If I’ve seen one part, I’ve seen them 
all’—whether [the product] is a rela- 
tional database, a CICS transaction, or a 
SOM class. That makes application 
development a whole lot easier.” 
Anderson says that PARTS is “set 
above the ‘language wars”, designed 
so that the underlying elemental parts 
can be built in C, C++, COBOL, or 
Smalltalk. “In the corporate world we 
find COBOL very popular; a lot of 
well-tested, proven code is still in use. 
No need to write new code—corporate 
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Error Manager 
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"I can’t reproduce it!" 


"Where should I put 
WinGetLastError?" 


WinDefWindowProc|) generated error 4610 [0x1702] 
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Figure 2 Parts Workbench; labels show. events and messages 


“Why does WinDefWindowProc 
generate an error? 


"It must be a 
configuration problem!" 


Stream Viewer 


Options 


-- Session started on 3/11/93 at 23:17:34 


Invalid switch handle 


in file BASEWIN.C at line 75. 
| |Suspect WinCreateStdWindow|) in file BASEWIM.C at line 103. 


- Works with optimized code in realtime situations. 


- Notifies your window procedure or callback function 


- Supports both PM and Fullscreen programs 
- Enables event-driven error handling 


- Invaluable for Debug, QA Test and Production cycles 


2224 East 21st Street 
Brooklyn, New York 11229 





) |Error occurred while processing WM_CREATE [0x0, Ox16CADFCC] 


DosRead|) generated error 109 [0x006D) - Broken pipe 
in fila PIPEHAND.C at line 2717. 
This occurred 10 consecutive times] 


Includes a PM Viewer, 
Pointer Validity API and a 
Free copy of Command Line 





America can join the world of objects, 
starting with what they’ve got.” 
COBOL programmers, he asserts, can 
make the transition to Smalltalk/V 
much more easily than they can to 
C++.” 

Anderson says that Digitalk’s 
PARTS experience is proving that the 
‘programming’ skill requirement can be 
lowered. Applications can be assembled 
from pre-fabricated parts; it is possible 
to construct a functioning application 
without writing any code, only draw- 
ing lines between events and messages, 
as shown in Figure 2. 


A New Software World of Parts. Ander- 
son uses the analogy of an automobile 
to explain the nesting of parts to con- 
trol complexity: “You can have parts 
assemblies. My car engine is a part, 
which has several parts, such as the 
carburetor, which has parts of its own, 
and so forth. [This metaphor] is a good 
way to think about and solve bigger 
problems.” 

Another way to solve the big prob- 
lems is with distributed objects, Ander- 
son continues. “Today, most objects are 
on the client, but we can easily envision 
them on the server too. We'll have the 
flexibility of redeploying the objects. 
This is what distributed SOM, or 
DSOM, is all about; it’s the underlying 
plumbing that makes it work. There is 
an opportunity for someone to devel- 
op higher-level tools, object adminis- 


linkage section, 
01 REQUEST. 


05 PART-TABLE occurs 20 times indexed by partidx. 


10 PARTNO pic 9(5). 


10 DESCRIPTION pic X(30). 


10 PRICE pic 9(5)9v99. 


10 QTYINSTOCK pic s9(4) comp. 


procedure division using 
by reference REQUEST. 


Figure 3. Property dialogue for a COBOL part 


Anderson next envisions the cre- 
ation of “business parts, objects with 
relevance to the operation of a business 
such as customer support, accounting, 
and so forth. If you understand how 
your business is changing, you'll be 
able to change and evolve your appli- 
cations to reflect it.” He praises the 
Workplace Shell’s implementation of 
object-oriented user interface princi- 


“We took all of the CUA ‘97 controls and 
created a PART for each one, so you can 
Just drag and drop a notebook or slider 
control right onto your screen. ~ 


10 


tration tools. Now that I’ve got objects 
all over the place, where are they, what 
are they doing, are there any prob- 
lems?” 


—Mike leng 


ples and imagines how easily it could 
be adapted to the concept of business 
objects: “I can do drag-and-drop with 
business applications—drag a cus- 





tomer object, drop it on a purchase 
order and it’s all filled out. This will be 
commonplace.” 

Mike Arrigo calls the client/server 
world “a lot of transaction processing, 
mission-critical applications, just as on 
the mainframe. [Applications] may 
come in many flavors and not dovetail 
naturally. Each part, whether in SQL, 
COBOL, or CICS, is created and run by 
people in the organization who know 
it best. Our wrappers let developers 
present their data graphically on the 
workstation without recoding. This is 
more than a ‘screen scraper’ product, 
where you capture a host screen and 
just redisplay it graphically.” (A prop- 
erty dialogue for a COBOL part is 
shown in Figure 3.) 


THE PARTS PEOPLE 

We talked with several key members of 
Digitalk’s PARTS development team: 
Mike Teng, vice president, Deborah 
Lewis, senior software engineer and 
team leader of PARTS Workbench for 
Windows, and Alex Dionysian, senior 
software engineer and team leader of 
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PARTS Workbench for OS/2. They 
explain the background and future of 
PARTS. 


OS/2 Developer: How did the PARTS con- 
cept come about? 


Mike: Originally, we set out to create a 
graphical layout tool for building GUI 
applications. Then we realized that lay- 
out alone wouldn’t be enough; other 
products do that. So we created links, a 
visual way to link events to messages, 
as Smalltalk/V does. 


Deborah: We also wanted this tool to 
be extensible. Up to now, most graphi- 
cal tools haven't done very well. 


Alex: One of our basic concepts is that 
we want to provide tools that match the 
complexity of the calculation—a sepa- 
ration of skills. Some functions, such as 
building the GUI, are simple and there 
are simple tools for them. Others are 
inherently complicated and require 
more complex tools. Let’s say that you 
felt you needed Smalltalk or C++ to 
express a particular function. You 
would encapsulate this complex part 
and pass it on to someone else who was 
building the overall application. 


Alex Dionysian, Deborah Lewis, Mike Teng 


Cust ID 


Cust Name 


Address 


| CustFields - Customer fields 





Figure 4. A nested part containing customer fields and a non-visual Btrieve part 


Mike; One stumbling block to a new 
object programmer is learning concepts 
such as inheritance, encapsulation, and 





polymorphism, PARTS lifts you above 
those concepts. 


So this application builder person isn't a 
programmer? 


Mike: The separation of skills means 
that in big companies you start with 
nonprogramming analysts—people 
who understand the process, can lay 
out the screens, and can specify the 
functions to be performed. Then the 
programmers go to work writing 
scripts or code for the individual parts. 
Deborah: Then they create a parts cata- 
log that lists all the component parts. 
The analyst selects and wires them 
together. 


Alex: Later, if the components all exist 
and the analyst decides to change the 
interaction with the user, that can be 
done without involving the program- 
mers. 


Mike: Speaking of usability, we took all 
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Introducing 
Graphics | 

Biitauelee 
Kit/2 


fui Airtine Reservations 


But don’t worry. It’s all in good clean fun. Because now there’s 
a fast, cost-effective way to create graphic, easy-to-use inter- 
faces for OS/2* 2.0 applications and tools. Introducing Graphics 
Interface Kit/2 (GIK/2), an AD/Cycle® product from IBM 
Programming Systems. 

GIK/2 makes it easy to produce and manipulate symbolic 
representations of data without writing a single line of Presentation 
Manager® code. It automatically generates C code, where 
you can link the graphic symbols to the application data 
they represent. This not only speeds up your development 
cycle, it also helps you create applications that are intuitive 
and easy-to-use. Simplify transaction systems. Make databases 
easy to access. Bring organizational charts to life. Track 
inventory with simple icons. Any application can be 
made easier with the right graphic front-end. And GIK/2 
can help you make it happen. 


"IBM, OS/2, AD/Cycle and Presentation Manager are registered trademarks of International Business Machines Corporation. ©1993 IBM Corp. 








For orders or additional information, please call 
| 800 IBM-CALL and ask for Department S71. If you 
need graphic proof, ask for our evaluation demo which, 
by the way, is rated G. 
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Gary Slattery, Software Developer, Computer Associates 


“The best platform for 
DOS and Windows.” 


“I develop software applications for a living 
and | think OS/2* is a great way to do 
business.” A 32-bit, virtual memory operat- 
ing system, OS/2 is the ideal platform for 
developing your DOS, OS/2, Windows™ and 
even host-based applications. 

With OS/2 you can boost the power of 
your favorite DOS and Windows tools, 


IBM and OS/2 are registered trademarks and Workplace Shell, C++, CommonvView, 

C Set/2 and OS/2 Crash Protection are trademarks of International Business Machines 
Corporation. All other products are trademarks or registered trademarks of their respective 
companies. ©1993 IBM Corp. 


plus take advantage of over 250 available 
OS/2 development tools and utilities. 


“It's a productivity thing.” 
“L use CA Realizer to prototype new 
graphical interfaces. | write code using 
CA C++™ and CommonView”™ (integrated 
with IBM’s C Set/2™ compiler) 
while | compile in the 
background. And when 
designing reports or 
planning schedules, 
I use CA-RET” 
OS/2's pre-emptive 
multithreaded multitasking dynami- 
cally manages CPU time so you can run 
DOS, Windows and OS/2 apps 
concurrently in different sessions 
with maximum efficiency. That 
means you can edit in one win- 
dow, compile in another, link in a 
third and test in a fourth. With OS/2 Crash 
Protection,” if one application goes down 
due to a bug, the rest youre working on 
wont. “heres no limit to what you can do 
with this system.... [t's definitely made me 
more productive.” 








The Development Platform of Choice 

* Enhanced development platform for DOS, Windows and 
OS/2 apps. 

* OS/2 Crash Protection for superior reliability. 


. Pre-emptive multitasking for increased productivity. 


* Virtual memory provides up to 512MB per session. 


* Flat memory model eliminates wrestling with segments. 
»M ultiple virtual DOS machines for concurrent app 
testing. 


° Object-oriented Workplace Shell is easy and intuitive. 








arrested q 
velopment. 


The object-oriented 
user interface—the Workplace 
Shell™ (WPS)—gives you easy control with 
direct manipulation of visual objects on 
your computer screen. And should you need 
assistance with anything, [BM’s Worldwide 
Developer Assistance Program is always there 
to help. 


"A developer's dream.” 
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Use OS/2 to increase productivity of DOS, Windows and 
OS/2 application development. 


With OS/2’s 32-bit architecture, you can 
push your 386 and 486 hardware to the limit, 


and develop spectacular multimedia i292 
~WINWNE - 
Magazine Award 


and enterprise-wide client-server jor Techical excellence 
applications. OS/2 lets you create : 
the widest range of applications, 
for a variety of platforms, for 
almost any size computer. Here’s 
your chance to develop truly 
revolutionary 32-bit applications. With 

OS/2, now theres nothing stopping you. 

‘To learn more, call 1 407 982-6408 
now, and get a free white paper on why OS/2 
is the ideal platform for your 
development efforts. 
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Operate at a higher level. 





of the CUA ‘91 OS/2 controls and cre- 
ated a part for each one, so you can just 
drag and drop a notebook or slider 
control right onto your screen. We 
actually wrapped, or encapsulated, the 
OS/2 control APIs so you are using the 
real thing, not a simulation. 


So some parts can contain or reference 
other parts? 


Deborah: The nested part facility lets 
the designer take a set of primitive 
parts and build on them. This is analo- 
gous to subroutines in conventional 
programming. 


Alex: For example, you could develop 
a set of parts for data-entry that resem- 
ble a company’s standard input forms: 
name, address, phone number, and so 
on. [Figure 4] Then you could nest 
those parts on pages of the company 
notebook. [Figure 5] 


Mike: Sometimes GUI applications can 
result in very cluttered screens. Nested 
parts make it easier to pick and choose 
just which functions you want to 
appear on the screen at any point in 
time. Just as structured programming’s 
nested subroutines made programs 
easier to read, nested parts make 
screens easier to use. 
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Figure 5. A customer application with a customer field part nested in a notebook part 


and create your own interface with. We 
provide some of these parts as tem- 
plates that are packaged and sold sepa- 
rately, such as our database, COBOL 
and CICS wrappers. Each of those 


“Just as structured programming’s nested sub- 
routines made programs easier to read, nested 
parts make screens easier to use.” 
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Alex: You still may have some applica- 
tion functions that are outside of your 
set of parts, such as a database program 
written in COBOL or C. These are espe- 
cially important in client/server appli- 
cations. We surface the functions in the 
external program as messages that you 
can link to from the PARTS Workbench 


—Mike Teng 


products comes with a parts catalogue 
that helps you create a user interface, 
access the database, issue SOL com- 
mands, and so on. The CICS wrapper 
accesses mainframe applications so that 
the user interface part can run on the 
OS/2 desktop. We also have 3270 and 
SOM wrappers in the works. We'll sup- 


port distributed SOM objects that can 
be shipped from the server to the client. 


AN EXPANDING PARTS MARKET 
A growing after-market includes add- 
on products from Digitalk and other 
companies. “There are several related 
products on the market today, and 
more are coming,” says Anderson. “In 
development we have a SOM part and 
a CICS part. The SOM part has an 
underlying SOM repository that con- 
tains all the SOM class definitions. You 
select a class and a part is generated 
with the interface defined by that class. 
You can immediately start to use it and 
connect it to other parts. Each generat- 
ed part is a fully functioning SOM part. 
For example, you could create a multi- 
media part and immediately open a 
sound or video file, play it, rewind it, 
and so forth. Similarly, a CICS part 
might be a typical transaction in a CICS 
application.” 

If you were developing a vertical 
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application, he adds, “you could sell 
your parts catalogue to other business- 
es in your industry. For example, a cat- 
alogue of banking components could 
2 used as a base for other, customized, 
Banking applications.” 












AM/V FOR COLLABORATIVE 

PROGRAMMING 

Team/V is an extension to Smalltalk/V 
at allows development teams to bet- 
r organize, structure, and coordinate 
veir work. Team/V gives Smalltalk 
: grammers a way to structure appli- 
tions into discrete pieces that can be 
viewed, manipulated, and maintained 
»parately. In the future, Team/V’s 
inction will be applied to the PARTS 
vironment. Today it is a Smalltalk/V 

ol. 





















EAM/V TALK 
lext, we spoke to Juanita Ewing, a 
iember of the technical staff and pro- 
ct leader for Team/V, based in Port- 
d, Ore. 


OS/2 Developer: How would two or more 
nalltalk/V programmers benefit from 
pam /V ? 


Juanita: Team/V provides structural 
pabilities to make it easier for teams 
# programmers to write applications. 
eam/V’s modular structures, called 
ackages, are the basis of work assign- 
ments and of sharing between team 
members. An example package may 
ave the function of printing, another 
e might do numeric calculations. 
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Let me make an analogy. Let’s say 
you had a group of cartographers 
working on producing a map of the 
world. But the world isn’t too stable 
and things keep changing. If you just 
turned everyone loose and let them 
change anything they wanted to, you 
would have chaos, multiple versions of 
the world map. The solution is to 
divide the map up into smaller, more 
manageable units. “Here, you take 
Europe. You take Africa.” It’s just a 
way of viewing 
or structuring 
an application. 

Furthermore, 
let's keep a ver- 
sion of each 
release so that 
you can go back 
in time. This is 
very important 
for traceablity 
and account- 
ability. “Show me the world in 1988.” 
Team/V does this through PVCS, 
which has become an industry stan- 
dard version control system. Source 
code is stored in packages (a unit of 
sharing) in a repository where other 
team members have access. This works 
for both vendors and corporate pro- 
gramming shops. 

We also added PARTS access to 
Team/V repositories; PARTS Work- 
bench developers can use the Team/V 
capabilities to save versions of parts, in 
addition to saving packages of 
Smalltalk code. 


Juanita Ewing 
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Dick Conklin, 3408 Sherwood Bivd., Del- 
ray Beach, Fla. 33445, (407/495-4421. Con- 
klin is the editor of OS/2 Developer. He 
recently retired from IBM after 20 years in 
engineering, education, marketing, and 
developer support. A member of the origi- 
nal IBM PC development team (DOS 1.1), 
Conklin is the author or general editor of 
five books on PC graphics, laptop comput- 
ing, and OS/2. 
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This article describes Network SignON Coordinator/2 (NSC/2), a productivity aid that provides a single logon 
and password change capability for users who deal with a variety of LAN and host accounts. BY BILL BANNING, 
MICHELLE BUENKER, GARY HORN, and JIM WANGLER 


Network SignON 
Coordinator/2: A Plus 
For Network Applications 


( etwork SignON Coordinator/2 (NSC/2) 
is a productivity aid that provides a sin- 
| gle logon and password change capabili- 
ty for users who deal with multiple local or gate- 
way host sessions (via 3270 or 5250 host terminal 
emulation, or APPC), multiple LAN servers (IBM 
and Novell NetWare), or one or more OS/2 Data- 
base Manager servers. 

Developers can tailor NSC/2 to their work 
environment to increase personal productivity. 
Its API, command line interface, and user exits 
allow its functions to be incorporated into appli- 
cation programs. The user interface is shown in 
Figure 1. 


FUNCTION 

NSC/2 1.1 allows users to log on to, log off from, 
or change passwords on a variety of systems, 
including hosts (VM, MVS and OS/400), local 
OS/2 UPM, OS/2 LAN Server domains, and Nov- 
ell NetWare file servers. 





Supported Configurations. NSC /2 can be configured 
as either client (OS/2 or DOS) or server. Users at 
OS/2 clients can benefit from the full range of 
functions available, while DOS users are more lim- 
ited in what they can do. Figure 2 gives an 
overview of the product's functional capabilities. 
The NSC client configuration is installed on 
OS/2 or DOS systems on which users initiate pass- 
word update or sign-on activity. Any workstation 
with installed NetBIOS support can also be con- 
figured as a client and perform various remote 


password operations via a remote workstation 
configured as an NSC server. 

Systems configured as NSC servers can receive 
and process password change and password veri- 
fication requests from DOS and OS/2 clients, pro- 
viding more flexibility with regard to host connec- 
tivity and extending the capabilities of client work- 
stations. 


NSC/2 controls password changes 
and access to mainframes and servers. 


The server component should be installed only 
on machines that will be used for one or more of 
the following: 


¢ They will locally process requests for UPM 
password changes from other client worksta- 
tions (as with OS/2 Database Manager 
servers). NSC, however, need not be installed 
on a LAN server that handles only LAN-relat- 
ed logon and password change requests from 
clients. 

¢ They will process requests from other client 
workstations for password changes on hosts 
attached to the remote system (in which case 
the system acts as a gateway to a host for other 
DOS and OS/2 clients). 

* The machine is one on which user or group 
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NSCO106 Host TEMPVM1 Signon for BUENKERM In progress. 
NSCO0100 Signon to session A complete. 
NSCO106 IBM LAN Server AUSLAND1 Signon for BUENKERM in progres 


NSCO100 Signon complete. 


NSCO106 Node SERVERNODENAME Signon for MMB637 in progress. 


NSCO100 Si 


non complete. 


Figure 1. Network SignON Coordinator/2 1.1 user interface on OS/2 


NSC program configuration infor- 
mation will be stored and main- 
tained, utilizing the server’s func- 
tion as a central repository for 
those files. 


CONFIGURING NETWORK 
SIGNON COORDINATOR FOR 
YOUR ENVIRONMENT 

Signon and password change activity 
performed by NSC is driven by defi- 
nitions in the NSC.INI configuration 
file that tell the program which 
accounts to act upon. Five major defi- 


nitions are available: LOCAL, LANSERVER, 
HOST, NODE, and SERVER. 


Scenario. An OS/? 2.0 user has user 
accounts on a variety of systems—the 


An OS/2 application can be launched from an 
NSC/2 signon screen. 


local UPM, three OS/2 LAN server 
domains (the user usually logs on to 
one but also uses resources on the other 
two), one NetWare file server, two local 
IBM host sessions (one via 3270 termi- 
nal emulation and the other via 5250), 
one host session through a remote gate- 
way via APPC (through which DB2 is 





accessed), and an OS/2 Extended Ser- 
vices Database Server. The user would 
create one definition for each of these 
accounts in the NSC.INI file. A sample 
NSC.INI file is shown in Figure 3. 

Notice that definitions that follow a 
SERVER statement are actually executed 
at the machine configured as an NSC 
server. In the example code in Figure 3, 
the database server has been config- 
ured as an NSC server and also acts as 
a gateway to the host (for instance, via 
the DDCS/2 product). The user syn- 
chronizes the password for the OS/2 
database account and the host account 
with the two definitions following the 
SERVER statement. The LOCAL statement 
ensures that all password changes will 
be done on the user account at the data- 
base server, and the HOST statement does 
the same for the host account. 


OS/2 DEVELOPER 


Some additional configuration activ- 
ity must be done for host support. On 
OS/2, NSC uses OS/2 Communica- 
tions Manager’s Emulator High Level 
Language Application Program Inter- 
face (EHLLAPI) to communicate with 
hosts connected via 3270 or 5250 termi- 
nal emulation. To tailor the logon and 
password change activity to their 
unique hosts, users create host infor- 
mation files using a script language 
provided by the program. The script 
language provides the flexibility for 
NSC to adapt to virtually any IBM host 
environment. Communication with 
hosts connected via APPC is more com- 
plex and involves creating or modify- 
ing network definitions at both the 
workstation and the host computer. 


CUSTOMIZING AND DEVELOPING 
APPLICATIONS WITH NSC 
Applications can be integrated with 
NSC in two ways. First, the Presenta- 
tion Manager (PM) interface can be 
used as the front end for an application, 
launching the application from user 
exit routines during signon, signoff, or 
password change activity. Keeping the 
PM interface active allows users to 
selectively sign on to and off from indi- 
vidual, configured locations. 

An application can also provide its 
own user interface to obtain the user ID 
and password, and then invoke NSC to: 


Ot 





Figure 2. Functional summary 


¢ Sign on to the user’s default loca- 
tions 

¢ Sign off from all locations at which 
a user is signed on 

¢ Change the password on the user’s 
default locations. 


NSC can be invoked by an application 
through either an API or the command 
line interface. 


User Exit Routines. Its user exit capability 
enhances NSC’s productivity in a vari- 
ety of environments. Exit routines, 
which are automatically started when 
a signon, signoff, or password change 
request is processed in NSC.INI, can be 
Figure 3. Sample NSC.IN| file either command files (started using the 
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command interpreter as windowed 
sessions) or executable programs. All 
' | exit routines are started in a separate 
session in either the foreground or the 
background and may be PM, full- 
screen or windowed applications (in 
DOS, exit routines must be noninterac- 
tive). 

Exit routines can be used for a vari- 
ety of tasks, including assigning or 
cleaning up redirected drives, logging 
on to or keeping passwords synchro- 
nized with other applications, or exe- 
cuting tasks associated with signon 
activity. 





Exit routines can be used 
for a variety of tasks, 
including assigning or 
cleaning up redirected 
drives, logging on to or 
keeping passwords 
synchronized with other 
applications, or executing 
tasks associated with 
signon activity. 





Figure 4. User exit for logging on at a DOS database client 


Figure 4 shows a sample user exit 
routine that could be run on a DOS 
Database Client (from IBM Extended 
Services 1.0). Since NSC does not 
specifically support DOS Database 
Client logons, a user exit can be imple- 
mented to perform this function. Note 
that the user exit statement is associat- 
ed with a NODE definition in the NSC.INI 
file. 


API Support. NSC/2 is shipped with a 
small toolkit that lets programmers 
incorporate the program’s functions 





Figure 5. NSCRSIGN API syntax 
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IBM Programming Systems introduces 
C Set++" the most complete application & 
compiler lets you unleash 

all the power of OS/2 — so you can 

It has an extraordinary code optimizer with a 
full set of options. Even a switch to optimize for the new 
classes and classes for multitasking, streams and more. 

There’s also a full complement of other helpful 

Analyzer traces the 
execution of a program, 
analysis. Plus a class 

What’s more, you get Workframe/2‘” a language- : 

independent tool that lets you customize your own envi- | Inter-module 


& ef 
development package you can buy for 
create the most advanced, high- 
Pentium™ processor. Plus a full set of class libraries, 
features. Such as = interactive source level debugger. 
then graphically displays 
ronment. It’s adaptable and flexible — you can use any 16 Optimization 


SSION 
O0S/2® Its 32-bit C/C++ Cr 
performance applications. | 
including application frameworks for PM, container 
And the unique Execution Trace 
diagrams of the Standards 
shows class library relationships. 
and 32-bit sis Windows™ ats OS/2 tools. 


Instruction scheduling 


To order C Set++, 
contact your nearest dealer or call 
1-800-342-6672 (USA) or 
1-800-4.65-7999 ext. 460 (Canada). 

Clearly, there’s only one place to start. C Set++. 
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IBM and OS/e are registered trademarks and C Set++ and Workframe/2 are trademarks of International Business Machines Corporation. Pentium is a trademark of Intel Corporation. 
Windows is a trademark of Microsoft Corp. © 1993 1BM Corp. 
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| Figure 6. Message callback procedure 





Figure 7. Application 's use OFNSCRSIGN API (continued on page 26) | 
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into their own applications. 

The NSCRSIGN API allows 16- and 
32-bit applications to take advantage of 
NSC’s capabilities. The application 
passes the API the type of request 
(signon, password change, or signoff), 
user ID, password, and the address of a 
procedure to be called for messages 
generated by the API. The application 
can display these resulting messages, 
write them to a log file, or perform 
other processes based on return codes 
associated with each message. Figure 5 
depicts the syntax of the NSCRSIGN 
API. 

Errors from the NSCRSIGN API are 
reported to the calling application via 
a message callback procedure. The 
address of this procedure is passed as a 
parameter to NSCRSIGN, thereby 
avoiding interaction with the user. This 
allows the use of either PM or full 
screen applications. 

The message callback procedure 
should be defined as shown in Figure 
6. Figure 7 illustrates a call to NSCR- 
SIGN with all messages written to stan- 
dard output. (If using the IBM C Set/2 
compiler, use the compiler option - 
DNSC32 to enable 32-bit definitions in the 
toolkit header file as well as in your 
source code.) 


Command-Line Interface. NSC’s com- 
mand line interface allows a REXX 
command file to take advantage of the 
program’s capabilities. The REXX com- 
mand file calls the command-line inter- 
face with the type of request (signon, 
signoff, or password change), user ID, 
and optionally a password and new 
password. NSC returns a return code 
indicating the overall success or failure 
of the call. Messages are written to 
standard output and may be redirect- 
ed to a file for more sophisticated error 
analysis. 
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TLIB Version Control 
For DOS, OS/2 and Windows-NT 


e The experts loved TLIB 4: 
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Master the art of multi-platform GUls. 

XVT Software is the leading choice of world-class 
developers for one reason: It is the simplest, quickest path 
to building quality applications that port to every GUI 
without compromises in look-and-feel or performance. 
Plus, it’s easier to learn and use than native toolkits, so your 
time and effort goes into your application, not your GUIs. 


XVT gives you simultaneous original GUIs. 
Because XVT uses native GUI objects, your application 
is indistinguishable from one written directly to the native 
toolkit, Through our layered architecture, you achieve 
equivalent cross-platform functionality appropriate to each 
GUI, without the overhead and inflexibility of proprietary 


emulation-based systems. 
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Interactive Design Tool and the XVT Portability Toolkit. 
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forms the most comprehensive and advanced solution 


for developing completely portable GUI applications. 


Developers judge XVT to be a masterpiece. 

XVT is the base document for the IEEE’s GUI 
standardization effort. Our thousands of customers include 
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The portable GUI development solution. 


1-800-678-7988 


XVT Software Inc. 4900 Pearl East Cir. Boulder, CO 8030) 
303) 443-4223 FAX (303) 443-0969 
For European inquiries, contact: Precision Software GmbH 
Phone: 49 061 03/37 940 Fax: 49061 03/3695 5 








this fall by IBM. BY PAT SCHERER 






The LAN Distance Product: 
LAN Application Transparency 
For the Remote User 


emote LAN access is a rapidly growing 
market already beginning to spawn new 
applications and influence application 
design. It also greatly influences how, and perhaps 
more important, where many of us do our work 
by breaking the tethers of the /ocal area network. 

IBM’s LAN Distance product is a new family 
of communication products that let remote users 
transparently run LAN-based applications over 
switched connections (asynchronous, synchro- 
nous, and ISDN) using public switch telephone 
networks or PBX/CBX exchanges. The primary 
distinction of the LAN Distance product is that it 
uses device driver replacement technology to pro- 
vide a superset of functions using non-dedicated, 
non-proprietary hardware. 

The LAN Distance product extends the LAN 
environment, with all of its applications and 
resources, to any user with access to a telephone. 
Most widely-used protocols and network operat- 
ing systems are supported. In addition, the prod- 
uct is designed to be readily extendable to new 
applications, hardware, and protocols. 

A remote workstation can connect to other 
remote or LAN-attached workstations. The LAN 
workstations are accessed via a software-based 
bridging, routing, and administrative component 
called the Connection Manager. The LAN Distance 
product's connection manager supports up to 32 
simultaneous communication ports and provides a 
wide range of configurable security and adminis- 
trative features. 
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REMOTE LAN ACCESS TECHNOLOGIES 

Other available remote LAN access products vary 
widely in cost and functions. The degree of func- 
tionality is decided in part by the technology cho- 
sen to provide remote access. The LAN Distance 
product uses a device driver replacement 
approach called “remote node.” Two other com- 
mon approaches are referred to as “remote con- 
trol” and “remote client.” 

With the remote control approach, a remote 
workstation dials into and takes control of a LAN- 
attached workstation. The LAN-attached station 
executes programs on behalf of the remote station. 
Only keyboard and screen data from the dedicated 
LAN-attached system is routed back to the remote 
workstation, minimizing the traffic flowing across 
the link. This approach has some disadvantages, 
however. A dedicated LAN-attached workstation 
is required for each remote workstation dialing 
onto the LAN, application transparency is not 
always preserved, and graphical interfaces, when 
supported, are not supported efficiently. 

The remote client approach is generally an 
extension of a network operating system that 
allows a remote client workstation to share data 
and applications located on a common network 
server. Application transparency and graphical 
interface support are generally preserved within 
the remote workstation. Disadvantages stem from 
the fact that the remote workstation is addressable 
only by the server to which it is connected; access- 
ing another server generally requires the user to 
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This article describes current remote LAN access technology along with specific features of the IBM LAN Distance product, introduced 
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oettings 


Figure 1. Settings notebook 


disconnect and redial. This approach 
does not scale well to support of large 
or distributed environments, as bottle- 
necks in memory and CPU capacity 
tend to form in the common server. 
Because of this, most products using 


the remote client approach are dedicat- 
ed servers supporting a limited num- 
ber of remote connections (usually 
fewer than 16). 

The LAN Distance product's remote 


node approach provides a more flexible, 
scalable solution for transparent remote 
LAN access. This approach replaces the 
device driver within a LAN-attached 
workstation (the connection server) and 
allows it to move data between the LAN 


Remote LAN access influences how and 
where we do our work by breaking the tethers 
of the local area network. 


and WAN. Remote node also provides 
full addressability, which allows a 
remote workstation to access distributed 
LAN-attached servers and peer services. 
The remote workstation can access 





information and services wherever they 
reside on the LAN, without the necessi- 
ty of redesigning the LAN with a cen- 
tral dedicated server to accommodate 
remote access. Increasing numbers of 
local and remote LAN users can be 
accommodated without duplicating 
(and maintaining) data files across 
numerous communication servers. 


ABOUT THE PRODUCT 

The LAN Distance product consists of 
two packages, IBM LAN Distance 
Remote and IBM LAN Distance Con- 
nection Server. The LAN Distance 
Remote package contains the code nec- 
essary to dial and accept calls from 
other remote workstations. The Remote 
package can provide a low-cost means 
for LAN applications to communicate 
without a physical LAN: if installed on 
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Figure 2. Phonebook and call status 


a LAN-attached file server, it can pro- 
vide indirect remote access to the LAN 
through shared files contained on the 
server. This configuration provides the 
functionality of the remote client 
approach. If used in conjunction with 
the Connection Server, a remote work- 
station can directly access any worksta- 
tion on the LAN configured to partici- 
pate in the remote environment. The 
Remote package runs on either OS/2 
2.x or Microsoft Windows 3.1. 

The IBM LAN Distance Connection 
Server provides administrative and 
security services in addition to routing 
frames between the WAN and LAN 
environments. While in small network- 
ing environments, the Connection Serv- 
er can reside on a non-dedicated sys- 
tem. A dedicated system is recom- 
mended for supporting large networks 
with moderate to heavy remote traffic. 
The Connection Server uses the multi- 
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Phone Book 


far CONNECT 14400 


tasking capabilities of an OS/2 2.x base. 

The LAN Distance product supports 
all hardware supported by the operat- 
ing system platform on which the LAN 


Distance component runs; including 


IBM and IBM-compatible 80386. and 
80486 systems. The product is: opti- 


LAN Distance consists of two components, the 
Remote Server and the Connection Server. 


mized for modem and channel speeds 
of 9600 bps and above. Most commonly 
used modems are supported via a sin- 
gle selection within the LAN Distance 
product settings notebook (shown in 
Figure 1), and many others, such as the 
Phone Book shown in Figure 2, can be 
configured by customizing the modem 
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settings found there. 

When accessing the WAN, a LAN 
adapter is nof required on a remote 
workstation, nor is a modem required 
on a LAN-attached workstation; com- 
munication between the LAN and 
WAN is accomplished via the connec- 





tion server. Modem sharing is also very 
cost-effective. 

The LAN Distance product includes 
support for the following connectivities: 


¢ LAN Connectivities—Token Ring, 


Ethernet 
¢ WAN Connectivities—ISDN Basic 
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Client/Server 
Database Solutions 


It’s available now—ready to per- 
form on your desktop. A new 
function-rich, 32-bit relational 
database you can really trust 
with your growing client/server 
network, your mission-critical 
data and your business. 
Introducing IBM DATABASE 2™ OS/2* 
(DB2/2™) from IBM Programming Systems, the 
birthplace of relational database technology. 
DB2/2 includes an industrial-strength DB 
engine that supports transaction management, 
concurrency control, security, integrity, and 
recovery functions. Designed to exploit the 
power and open architecture of OS/2, it also 
supports industry-standard SQL for developing 
portable applications. And it runs your DOS, 


DOS Windows™ and OS/2 , 
applications requiring 
online access. 
You can access data 
directly from DB2/2 on | 
your desktop or from a 
DB2/2 server on your , 


LAN, and with 








IBM, OS/2, DB2 and OS/400 are registered trademarks and DATABASE 2, DB2/2, DISTRIBUTED DATABASE CONNECTION SERVICES/2, 
SQL/DS and Information Warehouse are trademarks of International Business Machines Corporation. Windows is a trademark of 


Microsoft Corporation. © 1993 IBM Corp. 






DISTRIBUTED DATABASE 
CONNECTION SERVICES/2™ 
from DB2} SQL/DS™ and OS/400° 
databases as if they were on your desktop, too. 
This versatility can play a significant role in 
an Information Warehouse™ solution 


| for your business. 


We've developed an 
[O Se 
exciting demo diskette to show 
you just how well new DB2/2 
performs—right on your desktop. Call us today 
for your free demo, or to order DB2/2: 
1 800 342-6672; or fax: 1 800 445-2426. 
In Canada, call 1 800 465-7999, ext. 850. 
An upgrade from OS/2 Extended Edition 


or Extended Services is also available. 
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Rate Adapter, Asynchronous Com- 
munications Port, Dual Asynchro- 
nous Adapter, Asynchronous/Syn- 
chronous RTIC Adapter, Synchro- 
nous Wide Area Connector, X.25 
via modem. 


The LAN Distance product uses 
IEEE 802.5 source route bridging to 
support token ring connections and 
transparent bridging to support Ether- 
net. Because transparent bridging 
requires the Ethernet adapters to run in 
“promiscuous” mode, the number of 
WAN ports effectively supported on 
Ethernet will be less than that of token- 
ring connection servers. This overhead, 
due to the connection server's 
increased traffic filtering, is a fraction 
of that incurred if unfiltered traffic 
were allowed to flow over the WAN. 

The LAN Distance product allows 
the connection server to use other tech- 
niques to move frames to and from the 
LAN. To offset the processing overhead 
when using Ethernet or connecting dif- 
ferent LAN types, a higher layer router 
can be used. For example, with a 
TCP/IP or IPX protocol, the IP 
router/ gateway could be used with the 
LAN Distance product. The router 
would then determine which frames 
would be directed off the LAN to the 
WAN. 

The LAN Distance product’s bridg- 
ing functions provide extensive filter- 
ing capabilities, simple network man- 
agement protocol (SNMP) support, and 
[EEE 802.1d spanning tree algorithm 
and protocol (STAP) support. The latter 
is primarily intended for use in non- 
switched connection environments. 

The LAN Distance product also sup- 
‘ports high-speed synchronous non- 
switched connections via the IBM Wide 
Area Connector. These include up to 
two fractional Tl connections or a sin- 
gle T1, El, or J1 connection. 

The LAN Distance product also 
allows an asynchronous modem 
equipped with a PAD function to dial 
into an X.25 network. 


The LAN Distance product includes 
media access control (MAC) drivers for 
the first four WAN connectivities. 
Other adapters packaged with MAC 
drivers (such as the IBM wide area con- 
nector) that adhere to and support the 


NDIS interface can also be supported 
by the LAN Distance product. 

The LAN Distance product supports — 
all NDIS-enabled protocols; of those, it 
contains the following: 


Introducing RemoteVision. 
The Complete Software Solution 
For Remote Networking. 
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a Connect to remote offices with LAN-to-LAN 
dial-up networking. 

a Add remote connectivity services using 
existing LAN machines, 

m Access remote PC servers and hosts without 
additional host gateways. 

a No specialized hardware/adapters. 
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a Extend LANs transparently over 
| asynchronous modems to remote 
| workstations and workgroups. 
e Run DOS, Windows’, & 05/2" apps written 
| to multiple protocol stacks on remote nodes. 
a ()perate remote computers as full-function 
LAN nodes. 


RemoteVision makes it easy and affordable for DOS, Windows and 
OS/2 users in remote locations to connect to Token Ring or other LANs 
using dial-up modems. Response time remains fast, applications don’t 
need changing, and users won't need retraining. So you can turn your 

remote machines into full-function workstations. With RemoteVision. 
To immediately find out more, or to take advantage of our “Try Now, 
Pay Later” 30-day money-back guaranteed trial offer, call today. 





Technology inc. 


1265 Montecito Ave., Ste. 101, Mountain View, CA 94043 
Tel: (415) 965-8607, Fax info: (415) 965-8607, (then press 2) 


Trademarks are from their respective companies. ©1993 Token Technology, Inc. 001-0 








* Netbios 
® 802.2 
* ODI to NDIS mapper. 


Everything required to support 
these interfaces is included with the 
LAN Distance product. Users can 
transparently run any LAN applica- 
tions utilizing these interfaces within 
the WAN environment without modifi- 
cation. Applications such as IPX, 
TCP/IP, Person-to-Person, Lotus 
Notes, and OS/2 Communication Man- 
ager can be purchased and installed to 
run within the WAN environment. The 
LAN Distance product can also access 
an AS/400 via the AS/400 PC Support 
Program. 

The LAN Distance product is net- 
work operating system independent 


and is therefore not packaged with any 
specific network operating system. It is 
designed to support any network oper- 
ating system residing over the 802.2, 
Netbios, ODI, or NDIS. interfaces, 
including: 


® IBM LAN Server 
* Microsoft LAN Manager 
e Novell NetWare Server. 


The LAN Distance product's exten- 
sive configurable security options, 
enabled via the settings notebook, 
include: 


Workstation address identification 
Valid logon time intervals 
Password encryption and session- 
based user authentication 

Access privilege levels 

® Callback. 


In addition, the LAN Distance prod- 
uct transparently supports existing 
LAN and application-level security 
mechanisms. Security features originat- 
ing from applications, the network 
operating system, the operating system 
platform, and hardware run without 
modification. 


LAN Distance 1s used for remote access to 
e-mail, network administration, fleld support, 
video conferencing, data exchange, and 
remote database and file sharing. 


The LAN Distance product employs 
a standard object-oriented graphical 
user interface consistent with that of 
OS/2 2.1. The interface has been 
designed to be consistent across all 
supported operating systems and 
machine types, from Windows-based 
remote workstations to OS/2-based 
LAN-attached workstations. Only 
those selections appropriate to the 


user’s location and privilege level are 
presented. 

The graphical user interface pro- 
vides information on available servers, 
call status, and hypertext help. Connec- 
tion to the “virtual LAN” may be made 
by selecting an entry from a user's 
phone book, or through a command 
line interface. Commands may be 
entered from the keyboard or embed- 
ded in a batch or command file. 


LAN DISTANCE CALLING 

IBM uses the LAN Distance product to 
provide LAN access to its home termi- 
nal users and travelling personnel. It is 
applied to numerous other tasks, 
including remote network administra- 
tion, remote access to mail, field sup- 
port, video conferencing, remote site 
data exchange, and remote database 
and file sharing. 


Pat Scherer, /BM Corp., 11400 Burnet Ad., 
Austin, Texas, 78758. Scherer is a devel- 
oper and performance analyst with IBM 
LAN Systems. She joined IBM in 1980 as 
an industrial engineer, developing comput- 
er models for strategic planning. Her recent 
projects include OS/2 Communications 
Manager and the LAN Distance product. 
Scherer holds an M.B.A. in industrial man- 
agement and advanced certification in 
computer science. 
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OBJECT-ORIENTED - MULTIPLATFORM - SINGLE-SOURCE - C++ 


ZINC” APPLICATION FRAMEWORK™ 3.5 


Multiplatform Flexibility 
From One Application 


Framework. 


is an essential component in software design. Your 
development tools should allow you to easily incorporate new 
features and technologies into your applications without rewriting 
all of your code. That's a tall order if your development tools are 
designed like a straight-jacket. Zinc Application Framework 3.) 
and Zinc Designer” give you flexible and extendible support for 
Microsoft Windows, Windows NT, OS/2 2.0, UNIX Motif, DOS 
Graphics and DOS Text. And Zinc does it with ONE set of source 
code. Zinc's multiplatform, object-oriented architecture won't 


confine your application development options today... or tomorrow. 


FOR A FREE ZINC DEMO KIT, CALL US TOLL FREE TODAY AT 


1.800.638.8665. IN EUROPE CALL +44 (0)81 855 9918 
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Zine Software incorporated 
485 Gosth 100 East 
Pleasant Grove, Wah 
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UTAH 84062, TEL 801.785.8900, FAX 801.785.8996, BBS 80!.765.8997 


EUROPE: FINC SOFTWARE (UK) LIMITED 58-60 BERESFORD STREET, LONDON SEIS GBG, 
TEL +44 (0) 81 855 9918, FAX +44 (0) 81 3136 7778, BAS +44 (0) 21 317 2310 


© COPYRIGHT (992 ZINC SOFTWARE INCORPORATED, ALL RIGHTS RESERVED. ZINC, ZINC 
DESIGNER AND ZINC APPLICATION FRAMEWORK ARE TRADEMARKS OF ZINC SOFTWARE 
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“WE BUILT THREE VERSIONS OF OUR APPLICATION TO RUN ON EIGHT PLATFORMS. 
THERE’S NO WAY WE COULD HAVE GOT THAT PRODUCT OUT WITHOUT SOFTWARE 
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[fyou're facing an assignment as tough as Jim's, PVCS gives you the security of project-wide undo 
you're ready for The PVCS Series. and the confidence to create good code, knowing 
you've got a complete audit trail to show where you've 


If your development team has more than one member, neces 
been—and help plan where you're going. 


your application has more than one module or you're 
working on a LAN—you need automated software Operating seamlessly across Windows, NT. 
configuration management. MS-DOS, OS/2 and a variety of UNIX environments, 
The PVCS Series is your best choice for LAN-based PVCS is flexible enough to fit your development style 
Software Configuration Management (SCM). We'll and the most complex new applications. 

help you automate manual processes and avoid the The PVCS Series is the market leader in SCM for 
headaches that multi-version, multi-module applica» —_the LAN. It’s a complete family of products, designed 


tions can cause. for the widest variety of distributed client/server 
You can skip the lost data, the bug fixes that don’t stay development architectures and operating systems. 
fixed, the builds that include outdated modules, The PVCS Series includes: 


overwritten code and the frantic midnight phone calls PVCS Version Manager, PVCS Configuration Builder, The PVCS Graphical User 
about wrong versions that somehow made their way PVCS Production Gateway, PVCS Developer's Toolkit Interface makes it easy to 


into production. and PVCS Reporter. apply the power of PVCS 
Instead of wasting time wrestling with your Put the power of The PVCS Series to work inyourqistributed = 
development environment, you can concentrateon —_for you. Call for a free demo disk, evaluation, or a a lla all alle 


building quality applications, regardless of what copy of the whitepaper, “Software Configuration 
language, programmer workbench, methodology or Management: Choosing The Correct Interface”. 
operating system you're using. 


PVCS eliminates tedious housekeeping details and 


automates builds so they are consistent and error free. ( A Tl 8(0- 547-PVC , EXT, 4() 
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More than ever, network services are being made available by LANs. NetWare 4.0 for OS/2 can provide network 





managers with these services from OS/2 2.x. BY KYLE BIGLER, HEATHER STONE, and BART WISE 


Using NetWare 4.01 for OS/2 


any people implementing complex 
local area networks (LANs) are finding 
| that more and more network services 
are being made available via LANs. These require- 
ments continue to put a burden on the network 
hardware resources. In addition, many developers 
want to implement client/server solutions in the 
OS/2 environment that can interact with Novell 
NetWare file and print resources. 

NetWare 3.11 requires that server hardware be 
dedicated to NetWare and NetWare Loadable 
Modules (NLMs), applications written to run ona 
NetWare server. The latest version of NetWare, 
version 4.01, has an option that gives a new degree 
of flexibility to NetWare users. NetWare for OS/2 
permits the NetWare 4.01 server to be run in a 
nondedicated fashion. Now any application that 
runs on OS/2, either 32-bit, 16-bit, or DOS/WIN- 
OS2 emulation, can share the server hardware 
with NetWare. 

NetWare 4.01 for OS/2 uses the same source 
code and provides the same functions available in 
a dedicated NetWare server. NetWare 4.01 for 
OS/2 contains a set of add-on drivers that permits 
the native NetWare modules to be loaded in the 
OS/2 environment. The benefits of running the 
native NetWare modules in the OS/2 environ- 
ment are that NetWare NLMs can be run unmod- 
ified, NetWare device drivers can be run unmodi- 
fied, and the high performance and reliability of 
NetWare is maintained. 


CUSTOMERS 

NetWare for OS/2 is targeted at three categories of 
customers. The first group is customers who cur- 
rently have strategic applications in both OS/2 or 





DOS environments and NetWare. 

The second group consists of customers who 
wish to develop and use OS/2 as a client/server 
platform. Client/server applications can be devel- 
oped for OS/2 while maintaining the established 
file and print server capabilities of NetWare. OS/2 
client/server applications can share LAN adapter 
and disk resources with the NetWare server. 

The third group is cost-conscious hardware 
customers. Customers who are currently using or 
are planning to use multiple LAN servers can con- 


Now any application that runs on 
OS/2, either 32-bit. 16-bit, or 
DOS/WINOS2 emulation, can share 
server hardware with NetWare. 


solidate all LAN functionality on a single server. 
The nondedicated operation of NetWare 4.01 for 
OS/2 will permit other LAN-based applications, 
such as Lotus Notes, to operate on the same 
machine. This feature is especially important to 
customers who have many isolated networks in 
satellite offices. 


FEATURES 

Since NetWare for OS/2 is an add-on to the Net- 
Ware package, it provides all the features (except 
NLM memory protection) provided with Net- 
Ware: 
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NetWare directory services (NDS) 
New management capabilities 
Multiple language capability 
Enhanced security and auditing 
Routing and WAN improvements 
Data compression, sub-allocation, 
and data migration 

¢ CD-ROM and optical drive recog- 
nition 


ss o@ # @ @ 


Figure 1. NetWare 4.01 for OS/2 structure 


4.01 for OS/2 server looks the same as a 
dedicated NetWare 4.01 server. 


Concurrent Use of 0S/2. The preemptive 
multitasking capabilities of OS/2 allow 
other workgroup and communication 
applications, such as OS/2 Communi- 
cation Manager, OS/2 Database Man- 
ager, Lotus Notes, and so on, to run 





NetWare 4.01 for OS/2 can be accessed from 
OS/2, Macintosh UNIX, DOS, and Windows. 


¢ Graphical administrative tools 
¢« Electronic documentation. 


In addition to the features provided 
by NetWare 4.01, it is possible to realize 
additional benefits by installing Net- 
Ware in the OS/2 environment. 


Accessibility from all Platforms. NetWare 
4.01 for OS/2 can be accessed from the 
same platforms as NetWare 4.01 (OS/2, 
Macintosh, UNIX, DOS, and Windows). 
From a client perspective, the NetWare 


concurrently with the NetWare 4.01 
server. You may also choose to do 
work in an OS/2, DOS, or WINOQS2 
session while the NetWare server pro- 
vides file and print services for you and 
other users in your office. This capabili- 
ty gives network administrators the 
flexibility of managing servers locally 
or remotely. 


Client/Server Application Development 
Flexibility. Application developers have 
the flexibility to develop NetWare- or 


OS/2-based client/server applications. 
All NetWare NLMs that have been cer- 
tified for NetWare 4.01 will run 
unmodified on NetWare 4.01 for OS/2. 
NLM development for NetWare 4.01 
for OS/2 is supported with the Net- 
Ware 4.01 software developers kit. 
OS/2 client/server applications can 
access NetWare file and print resource 
in addition to sharing server hardware 
resources, 


High Performance. The NetWare 4.01 for 
OS/2 server can achieve up to 92% of 
the performance of a dedicated Net- 
Ware server. The small overhead of 8% 
is due to the fact that OS/2 is now han- 
dling all hardware, interrupt, and I/O 
services. The optimization of these ser- 
vices in OS/2 and the streamlining of 
the NetWare 4.01 for OS/2 add-on 
modules results in the small overhead 
numbers. 


Dynamic Performance Tuning. This para- 
meter lets you specify what portion of 
CPU time is available to NetWare; the 
remaining CPU time is used by OS/2. 
The performance may be tuned while 
the server is running by using the 
graphical monitor utility provided with 
NetWare 4.01 for OS/2. This parame- 
ter may also be set to an initial value 
via the NET.CFG file. 


Graphical Monitor Utility. NetWare 4.01 
for OS/2 includes a graphical monitor 
utility that runs as an OS/2 application. 
This utility monitors the activity of your 
NetWare server and provides some of 
the same statistics provided by the MONI- 
TOR NLM. The statistics are displayed in 
graphical and numerical format. You 
can also use this utility to dynamically 
adjust performance parameters, memo- 
ry parameters, and to turn off or on the 
NetWare server alert beep. 


ARCHITECTURE 

NetWare 4.01 for OS/2 runs as a paral- 
lel operating system to OS/2. It runs at 
ring 0 with a protected block of memo- 
ry dedicated solely to NetWare. Net- 
Ware 4.01 for OS/2 comprises, in addi- 
tion to the Native NetWare 4.01 code, 
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three modules. A virtual device driver 
(VNETWARE.SYS), a physical device 
driver (PNETWARE.SYS), and a 32-bit 
ring 3 OS/2 application (NWOS2.EXE). 
Figure 1 illustrates the relationship 
between these three modules, the 
native NetWare 4.01 code, and OS/2. 
NetWare 4.01 for OS/2 also provides 
the capability to share disk drive, printer, 
and LAN adapter resources. At the pre- 
sent time, it is not possible for OS/2 and 
NetWare 4.01 for OS/2 to share an opti- 
cal drive. Any CD-ROM subsystem must 
be dedicated to either NetWare or OS/2. 


PNETWARE.SYS 

PNETWARE.SYS is an OS/2 physical 
device driver that communicates with 
and controls devices though architect- 
ed OS/2 system calls. This driver has 
the responsibility for handling inter- 
rupts, memory allocation, and screen 
notification. 


Registering and Unregistering Interrupts. 
The system interrupt controller is 
owned by OS/2, and NetWare must 
register for the interrupts it intends to 
use through the architected OS/2 
DevHelp routines. PNETWARE.SYS initi- 
ates the OS/2 Devielp routines to regis- 
ter and unregister the interrupts being 
used by NetWare. 


End of Interrupts. All first-level interrupt 
handling is performed by OS/2. When 
an interrupt occurs, it is first handled 
by OS/2 and passed to NetWare. All 
drivers are required to issue an OS/2 
DevHelp call to signal that the interrupt 
controller can be reset to issue another 
interrupt when one occurs. DOS device 
drivers handle this by writing directly 
to the interrupt controller. Since OS/2 
owns the interrupt controller, this func- 
tion must be accomplished using an 
architected OS /2 DevHelp routine. 


Memory Allocation. Memory for Net- 
Ware 4.01 for OS/2 is allocated by 
PNETWARE.SYS in one contiguous 
block. Once this memory is allocated, 
this block is no longer available to 
OS/2 or to OS/2 applications. This 
memory is also locked down and can- 
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not be swapped out by OS/2. NetWare 
uses physical addressing; it is crucial 
that memory for NetWare always be in 
the same physical location. 

The amount of memory to be allo- 
cated for NetWare is defined in the 
NET.CFG file. This memory can 
optionally be defined so it is released 
to OS/2 when the NWOS82.EXE process 
is terminated. 


VNETWARE.SYS 

VNETWARESYS is an OS/2 virtual 
device driver that controls NetWare’s 
interface to the server hardware. This 
module communicates with NW- 
OS2.SYS, PNETWARE.SYS, and OS/2 
to perform tasks on behalf of the server. 
Implementation as a virtual device dri- 
ver is required to obtain flat 32-bit 
addressing at ring 0, which is required 
for the NetWare operating system. 


Interrupt Support. VNETWARE.SYS con- 
tains the interrupt processing routines 
for the NetWare server. These routines 
are called by PNETWARE.SYS, which 
contain the second-level interrupt pro- 
cessing routines for the interrupt levels 
used by NetWare. Interrupt registra- 
tion and end-of-interrupt signaling are 
done in the PNETWARE.SYS module. 


Memory Management. The block of mem- 
ory allocated by PNETWARE.SYS is 
managed by VNETWARE.SYS and Net- 
Ware. VNETWARE.SYS5 is the loader for 
the NetWare server NLMs. Figure 2 
shows how NetWare 4.01 for OS/2 uses 
memory. 


Screen Management. The NetWare con- 
sole screen is managed by communica- 
tions with NWOS2.EXE. VNET- 
WARE.SYS updates the console and 
then unblocks an NWOS2.SYS thread. 
NWOS82.SYS issues the proper OS/2 
call to update the screen. 


Keyboard Functionality. VNETWARE 
receives information on NetWare con- 
sole keystrokes from an NWOS2.SYS 
thread. These keystrokes are then 
processed as they would be on a native 
NetWare 4.01 server. The exceptions to 


1893 


this rule are the Ctrl-ESC and Alt-ESC _ 
keystrokes. In NetWare 4.01 for OS/2, 
you use Ctrl-N and Alt-N to perform 
the equivalent function. The Ctrl-ESC 
and Alt-ESC keystrokes have special 
meanings in OS/2. 


Cache Buffers 


Permanent Memory | 
(8000h bytes) 


Stack | 
(8000h bytes) 


VNETWARE.SYS 


PNETWARE.SYS 








Figure 2. NetWare 4.0 for OS/2 Memory Map 


Timer Support. All timer processing is 
done in VNETWARE.SYS. 


NW0OS2.EXE 

NWOS82.EXE is a 32-bit ring 3 OS/2 
application. This module serves as the 
interface between the user and Net- 
Ware. NWOS2.EXE contains four main 
threads of execution. These threads are 
dropped down to VNETWARE.SYS 
and blocked until servicing is 
required. NWOS2.EXE can be run 
from either a full screen or windowed 
OS/2 session. 


Main Thread. The server's main thread 
of execution is used to load and run the 
server. When NW0S2 is entered from the 
OS/2 command line, this thread is 
dropped down to VNETWARE.SYS 
and used as the thread of execution for 
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the NetWare server. 

This thread is blocked if there is no 
work for the server to do or when the 
server is busy, according to the perfor- 
mance tuning parameter selected by 
the user. 


File 1/0. This thread performs local and 
redirected file accesses on behalf of the 
NetWare server. All file system I/O 
must be done at ring 3. VWETWARE. 
SYS unblocks this thread when O5/2 
file 1/O is required. 


Screen Handling. Updates of the Net- 
Ware console screen are made via the 
screen handling thread when the server 
runs in an OS/2 window. NWOS82.EXE 
issues the proper OS/2 ring 3 screen- 
handling function when VNET- 
WARE.SYS unblocks this thread. 


Keyboard. User keystrokes in the OS/2 
session containing the NetWare con- 
sole are passed down to the server 
using the NWQOS2.EXE keyboard 
thread. 


Disk Sharing. DSKSHARE.DSK allows 
NetWare to use disks controlled by 
OS/2. This driver provides an interface 
between NetWare and an OS/2 disk 


device driver. When DSKSHARE.DSK 
is used, there must be a primary parti- 
tion on the hard drive that can be dedi- 
cated to NetWare. The NetWare parti- 
tion of the disk is formatted and man- 
aged by NetWare. The relationship 
between DSKSHARE.DSK, NetWare, 
and OS/2 is shown in Figure 3. 
DSKSHARE.DSK is only for shared 
hard drives. Other disk devices, such 
as CD-ROM drives, can be installed 


Figure 3. NetWare 4.0 for OS/2 Disk Sharing 


and dedicated to either NetWare or 
OS/2, but they cannot be shared. 

For security reasons, the DSK- 
SHARE.DSK driver does not allow 
transparent access between the Net- 
Ware and OS/2 partitions. OS/2 appli- 
cations can use the space dedicated for 
OS/2 file systems; NetWare uses the 
space dedicated to the NetWare file 
system. OS/2 applications may access 
the NetWare file system by logging in 
through a NetWare OS/2 client. This 
protects your NetWare files from unau- 
thorized use. 


Memory tor NetWare 4.0 for OS/2 is allocated 
by PNETWARE.SYS in one contiguous block. 
Once this memory |s allocated. the block is no 
longer available to OS/2 or to OS/2 applications. 


Similarly, NetWare clients can only 
access OS/2 files by logging into the 
OS/2 distributed application or by 
physically using the OS/2 computer. 
This protects the distributed applica- 
tion information. 


Printer Sharing. Printer services for Net- 
Ware 4.01 for OS/2 are provided by 
OS/2. NetWare for OS/2 supports 
sharing of all printer types supported 





by 05/2. Load NPRINTER.NLM on 
the NetWare server to configure the 
attatched printers. When a print job is 
submitted, NWOS2.EXE will use the 
OS/2 print queue APIs to manage the 
print jobs sent by client workstations. 
From a client perspective, printing is 
managed exactly the same as on a 
native NetWare 4.01 server. 


LAN Adapter Sharing. NetWare 4.01 for 
OS/2 can share a network board with 
the NetWare clients on the OS/2 side 
of the computer using two different 
methods: 


1. Internet protocol (IP) or internet- 
work packet exchange (IPX) proto- 
cols can be sent to the server and 
other NetWare servers using the 
LANSHARE.LAN and _  LAN- 
SHARE.SYS modules. This method 
uses the IP routing function built 
into the NetWare server. 


2. All frame types can be sent to the 
server side using a virtual token 
ring driver (TOKENSHR). A bridge on 
the server, BRIDGE. NLM and 
VBRIDGE.LAN, can be used to 
bridge frames to the NetWare serv- 
er and the external network. This 
method can only be used if the 
server has a token ring connection 
to the external network. 


Each of these methods works by set- 
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The only mistake tritus SPF can't undo is 
your buying another text editor 
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ake no mistake about it, only Tritus SPF 1.2.5 has 
unlimited UNDO/REDO. Tritus SPF is the power- 
ful PC version of the mainframe editor ISPF/PDF 
and uses the same keystrokes. Features include modifiable 
panels, keyboard mapping, and integration with Micro 
Focus Workbench and WorkFrame/2. 

REXX edit macros use new optimization techniques for 
increased performance. You can edit files up to 256 MB in 
size and 64,000 bytes in width using standard record 
delimiters, custom delimiters or no delimiters. CUT and 
PASTE using private or public clipboards (Windows, OS/2) 
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with append or erase options. A new RECORD mode cap- 
tures keystrokes automatically and assigns them to a key 
for playback or future editing. All features, including 
REXX, work in DOS and OS/2. 

Tritus SPF 1.2.5 is available now for $99 plus shipping 
and includes a free upgrade to version 2.0 with Dialog 
Manager. Also included is an OS/2 32-bit version and over 
600 pages of documentation. The Prentice-Hall REXX 
Language book is available for an additional $25. 

We offer a 60-day money back guarantee. To order, call 
1-800-321-2100 for same day shipping. 
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Figure 4. NetWare 4.0 for 0S/2 LAN Adapter sharing 


ting up a virtual LAN connection on 
the OS/2 side that communicates with 
the link support layer (LSL) in the serv- 
er. Most OS/2 protocols are non-IPX 
and NDIS (network device interface 
specification) based and thus require 
that the TOKENSHR solution be used, 
These adapter sharing methods 
allow an OS/2 NetWare client to oper- 
ate on the same machine as the Net- 


Ware for OS/2 server. It is possible to 
login to the server from an OS/2 client 
on the same machine. 

Figure 4 shows the relationship 
between OS/2 client protocols and 
drivers to the NetWare 4.01 server 
ODI drivers. 


INSTALLING NETWARE 4.01 

FOR 0S/2 

NetWare 4.01 for OS/2 is easy to install 
and requires only a few steps in addi- 
tion to those required for native Net- 
Ware 4.0: 


1. Install OS/2 and leave a free space 
that can be formatted by NetWare. 
If you have already installed OS/2, 


The NetWare 4.0 NWOS2.EXE program Is a 
32-bit ring 3 application that serves as the 
interface between the user and NetWare. 


you can obtain free space by delet- 
ing a partition or adding another 
hard drive. 


2. Install and configure the NetWare 
4.01 for OS/2 support modules. 
3. Install and configure the NetWare 





client. This step is required only if 
you want to use this machine as 
both a client and a server. Figure 5 
shows the sections relevant to Net- 
Ware for OS/2 from the CON- 
FIG.SYS and NET.CFG files. In the 
NET.CFG, the server is specified to 
use 8MB of memory and have a 
tuning level of 7. The server will 
release the memory that was allo- 
cated at boot time when the user 
exits the server. 


4. Reboot the computer. 
5. Install NetWare 4.01. 


6. Define users and manage your net- 
work as instructed in the NetWare 
4.01 documentation. 


Installing NetWare 4.01 for OS/2 
adds about five minutes to the process 
of installing and setting up a native 
NetWare 4.01 server. This does not 
include the time required to install 


OS/2. 
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Figure 5. NET.CFG and CONFIG.SYS files 


FUTURE DIRECTIONS 
Over time, changes are being planned 


integration with OS/2. 


for NetWare for OS/2 that willenhance O5S/2 IFS Support. In the future, any 
its usability and increase the level of OS/2 installable file system (IFS) will 


Universal Document Imaging— 
An Open Solution 


Magus View™ — The revolutionary new PostScript-language 
rendering library from Magus. Virtually all business software 
can generate PostScript output; PostScript is the universal 
language for the device-independent representation of graphics 
and text. Now you can create programs which display or print 
documents from any source, without need for the originating 
application, proprietary file formats, or a PostScript printer. 


* Create front ends for document imaging systems — display 
PostScript files, or use PostScript as the image definition language 


* Enhance collaborative applications such as electronic mail or 


other “groupware” — support documents with complex graphics 
and fonts 


* Create host-based PostScript drivers for non-PostScript printers 


* Bring a new level of fidelity to print-previewing in your applications 


Magus View is available in DLL form for OS/2 2.0 and Microsoft 
Windows 3.1. Programming interfaces are provided for C, Smalltalk, 
and Digitalk’s PARTS Workbench. Prices start at $495 for a single 
Magus View Developer’s Kit. 


PO Box 390965 « Mountain View CA 94039-0965 =» USA 
(800)848-8037 * (415)940-1109 + fax (415)940-1238 esales@magus.com | 





be mountable to NetWare. This will 
provide a NetWare client the ability to 
access any disk partition in the sys- 
tem. This capability can also provide 
interprocess communication between 
NetWare NLMs and OS/2 applica- 
tions. 





Remote Installation Support. NetWare for 
OS/2 will be enabled for remote instal- 
lation. This feature will give network 
administrators added flexibility in 
managing NetWare 4.01 for OS/2 
servers. 


Memory Protection for NLMs. NetWare 
NLMs will be able to run in protected 


mode identical to the way native Net- 
Ware 4.01 has been implemented. 


Now Shipping.... 


NDP OS/2 2.1 


Developer's Pack 


$595 Includes: 
¢ 32-bit Globally Optimized Code 
e 32-bit Graphics and API Access 
¢ IBM Toolkit and Workframe | 
«Integrated Development Environment | 
« 1500 pages of documentation 
* Your Cholce of Compller: 


NDP CiC++, NDP Fortran-77 
or NDP Pascal 


Call for our White Papers on OS/2, i860 
Parallel Processing on PCs, Fortran 90 and 
our port of LAPACK to the 486 and i860. 


Microway * 
Research Park, Kingston, MA 02364 USA (508) 746-7341 | 
U.K., 081-541-5466 USA FAX (508) 746-4678 


Catch 


This just in. Applications Manager, best known as 
AM,.™ has just added OS/2* 2.1 support. We repeat, 
the flagship client/server application develop- 
ment software from Intelligent 
Environments is now available for 
OS/2 2.1 environments. 

For the latest-breaking devel- 


= ~ ose y- opments, we take you to corporate 

; America, where AM and OS/2 ofter Z 
a tried and tested mechanism for building 32-bit, 
multitasking, line-of-business client/server appli- | 
cations. AM’s visual programming environment 7 


streamlines the development and maintenance of 
mission-critical client/server applications by teams 
of programmers. And Static SQL support makes 
AM a real headliner. 

This recent news is becoming quite a feature 
story. By interfacing with 
MMPM/2, included 
with OS/2 2.1, AM lets 
programmers employ 
innovative team 
development 
capabilities 
like dynamically linked programming—simplhifying 
reuse and maintenance of program code. DDE Use AM to develop your own highly rated network programs. 
support allows programmers to paste information, 
including AM code, comments and AM-generated 
documentation, into Windows™ 3.1 applications 
easily. And there’s also quicker screen interaction 
and improved productivity through support for a = tue ha 2c 
OS/2’s new high-performance 32-bit graphics lo order or to lind out more about OS/2 2.1 or 
engine. AM, call 1 800 3-IBM-OS2. In Canada, call 

With AM and O3S/2, you'll never again have to 1 800 465-7999. : er 
return to your regularly scheduled programming. Operate ata higher level. 













SE  :, 
IBM and OS/2 are registered trademarks and “Operate al a higher level” is a trademark of International ee es ee 
Business Machines Corporation. AM is a trademark of Intelligent Enviranments, Inc. 2 Highwood Drive, = a, Saas 
Tewksbury, MA 01876. 1508 640-1080 or 1 800 669-2797, Windows is a lrademark of Microsoft = ee ee 
Corporation. @ 1993 IBM Corp — a 
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manager for NetWare 4.0 for OS/2. He has 
nine years’ experience developing LAN 
hardware and software. Bigler has a B.S. 
in electrical engineering from Ohio State 
University and an M.S. in electrical engi- 
neering from Rice University. 


Heather Stone, Novell Inc., D-21-3, 122 E. 
1700 S., Provo, Utah 84606. Stone is the 
product manager for NetWare 4.01 for 
OS/2. She has seven years of technical and 


How are you going to test your client/server apps? 


Check one: 
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It's not a trick question, but testing client/ 
server applications can be a tricky business. 
Traditional, manual methods can't stand up to 
the complexities of client/server. And most 
automated testing tools provide only a partial 
answer — concentrating on the GUI desktop, 
and leaving the rest of the client/server testing 
puzzle for you to piece together. 













(A The Softbridge 


Automated Test Facility 


Only the Softbridge Automated Test Facility 
(ATF) is designed to cover all aspects of 
client/server testing — GUI, distributed 
systems, legacy applications. If you're doing 
client/server development, maybe it's time 
you checked out ATF. To find out how ATF 
can help with your client/server testing needs, 
call 1-800-955-9190. 










_/, Softbridge, Inc. 
125 CambridgePark Dr. 
Cambridge, MA 02140 
617-576-2257 (Phone) 
617-864-7747 (FAX) 








Previous articles in this series discussed issues of control design. This article is the first of two to present 
advanced contro! design issues, with a focus on understanding and using color. BY CHRIS ANDREW, MARK A. 
BENGE and MATT SMITH 


A Color-Full Example: 
Using Color In Control Design 





Matt Smith 


ur previous articles explained the princi- 
ples of designing and constructing basic 
custom controls, illustrated through con- 
trols that can be used in everyday applications. 
Now, with a solid design foundation under our 
belts, we dive into the advanced control design 
areas of color, threads, clipping, and memory pre- 
sentation spaces. We will utilize this control within 
a Workplace Shell object called a color selector. 
Source code for the control can be found on the 
electronic sources listed at the end of this article. 





COLOR THEORY 

Before trying to construct a color selection control, 
we must first understand the basics of color theory 
as it relates to computer graphics. The following 
background information is excerpted from Com- 
puter Graphics, Principles and Practice, Second Edi- 
tion, by James Foley et. al. 

Computer graphics primarily uses five different 
color models: RGB (red, green, and blue), CMY 
(cyan, magenta, and yellow), YIQ (U.S. commer- 
cial color television broadcasting model), HSV 
(hue, saturation, and value) and HLS (hue, light- 
ness, and saturation). More information on these 
color models can be found in Computer Graphics, 
Principles and Practice. 

Of the available models, the RGB model is used 
in OS/2 Presentation Manager and by IBM’s and 
other manufacturers’ display and graphics cards. 
In the RGB model, color is an additive process; col- 
ors are made up of a combination of the three 
available primary colors red, green, and blue. Due 





to their additive characteristics, these three colors 

can combine to make other desired colors. 
Despite the use of the RGB model in computer 

hardware, however, the model we are most inter- 





Figure 1. Hue, saturation, and value color model 
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ested in is HSV, diagrammed in Figure 1, Also 
known as HSB (B for brightness), HSV can be con- 
ceptualized as a spectrum of colors radiating coni- 
cally from a central axis, as shown in Figure 1. For 
our purposes, we will take a cross-section of the 
cone; the remaining portion corresponds to artists’ 
tint, shade, and tone ideals, Since we are using a 
cross section of the cone, the value component will 
be at the same level. (In our example, we will use 
V=1.) 

Foley et. al. describe color theory by assigning a 
value between 0 and 1 for the saturation (S) and 
value (V) components. Hue (H) is a value between 
0 and 360, corresponding to the degrees of a circle. 
Blue, for example, is represented as H=240, S=1, 
V=1. For white, S=0 and V=1; H can be any value 
between 0 and 360. When S and V equal 1, they 
represent the artist's concept of “pure pigment,” 
the starting point for color mixing. When white is 
added to the mixture, the S value decreases, creat- 
ing tint. Decreasing the V value while S=1 creates 
shade. Tones are created when both V and S are 
decreased. 

A selection bar for the value component is pro- 
vided in the example source code but we will limit 
the discussion to the wheel itself. 

Figure 2 shows the model for our color wheel. 
It is broken down into six sectors corresponding to 
the HSV color space. Corresponding colors for 
Hue are shown at 60° intervals along the wheel. 

Our method of calculating corresponding RGB 
color is derived from Foley’s algorithm HSV_TO_RGB. 
To calculate a RGB-based color within Sector 1, the 
formula in Figure 3 is used. 


GOING FROM THEORY TO PRACTICE 
While in the previous model a color’s value can 
range from 0 to 1, within OS/2 Presentation Man- 
ager, color is represented on a scale from 0 to 255. 
We must therefore adapt Foley’s algorithms to 
work within the Presentation Manager's range. 

For saturation, which corresponds to the radius 
of the circle, we will set our range from 0 to 100. 
For V, we will use a constant value of 1, which 
leaves a color at its brightest level, allowing no 
shading. 

Using the method for RGB calculation, our 
color model would be described as shown in Fig- 
ure 4. 
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Figure 4. RGB calculation with a saturation range of 0-7 


Figure 2. Color wheel model 
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We must also draw the color wheel using the 
OS/2 Presentation Manager Gpi APIs. With a solid 
color rendering such as this, we need to determine 
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how to draw a given color. 
For illustration purposes, let's 


fy }] assume that Hue is in increments of 10° 
—! and Saturation is in increments of 25, 


as depicted in Figure 5. We end up 
with four drawing areas with the first 
and last requiring special handling. 

We will draw each of the areas in 
succession, using information from the 
previous area. The first area, which is 
shaped differently and does not have a 
previous area, must be treated as a spe- 
cial case. For drawing each of the line 
and curve segments, we use four Gpi 
APIs: GpiSetArcParams, GpiMove, GpiPar- 
tialirc, and Gpiline. To fill the area with 
the desired color, we use GpiSetColor 
along with the GpiBeginhrea and GpiEn- 
direa APIs. We will also use GpiCreateL- 
ogColorTable and GpiQueryCurrentPosition 
to place the presentation space into 
RGB mode and to determine the cur- 
rent drawing position after drawing the 
curved segment. 

We aren’t using the palette manage- 
ment in OS/2 Presentation Manager 
because not all video hardware has 
palette support yet. (XGA does, but 
VGA doesn’t.) And the palette docu- 
mention in the OS/2 toolkit is woeful, 
to say the least. 

Figure 6 shows line segment and 
drawing direction. With the Gpi APIs, 
Area 1 requires no calculation of points. 
All we have to do is move to the origin 
of the circle, then draw the partial arc 
and the closing line segment. In Figure 
7, we have shown all the Gpi API calls 
required to draw Area 1 as if it were a 
stand-alone figure. In the actual con- 
trol, we call the GpiCreateLogColor table 
only once, when we enter the routine 
that draws the color wheel. 

After placing the presentation space 
into RGB mode, we set the color in 
which the area is to be rendered with 
the GpiSetColor API. We then start the 
area by issuing the GpiBegindrea call. The 
concept of areas allows us to render the 
wheel in many colors when we issue 
the corresponding GpiEnddrea. (The 
drawing commands used to describe 
the area are used to determine the area 
to be filled with the color specified in 





Figure 5. Drawing method 


Figure 6, Area 1 drawing method 


the GpiSetColor API.) 

In Figure 7, GpiPartialArc draws line 
segment ab for use along with the 
curved segment bc. We then use GpiLine 
to draw the line segment ca and issue 
GpiEndArea to render the area. 

For Areas 2 and 3, the drawing 
method is more complex: we must 
determine points using trigonometry. 








Figure 8 shows the drawing method 
and Figure 9 is a code sample that per- 
forms the process. 

First, we determine the characteris- 
tics of arc be and set them up with 
GpiSetircParams. We then calculate loca- 
tion a with trigonometry, based on the 
previously drawn arc radius from Area 
1. Once a is determined, we move to it 
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Now there’ a faster, easier, more affordable way e 6 or 









to test your applications. Introducing Workstation 
Interactive Test Tool (WITT) 2.1, for OS/2° 2.0, An 
AD/Cycle product from [BM Programming Systems. 





WITT does it all. Record, edit, playback and screen compare. 
So once you ve built a test case, 
Fitrouine: ing’ you can use it over and over again. 


Workstation 


It works for applications on OS/2 
PM, and host-connected MVS, VM, 
Interactive VSE and OS/400° 
‘lest lool 2.1 Now regression testing is more 
reliable. New code testing is easier. 
® And learning is easier, too. With a friendly online tutorial. 


instant replay, 


What's more, WITT won't test your budget. Because it’s very 
affordable. 

It only takes an instant to call 1 800 860-2047, ext. WT1, and 
ask for more information and our free evaluation demo. Or, better 
yet, order WITT today with a no-charge two-month testing period 
and developer hotline assistance. 


ie The instant you get WITT 2.1, you'll be more productive. 


The development team at IBM Santa Teresa | 
created WITT 2.1 to help you improve the ) 
quality of your applications. | 


IBM, 05/2, AD/Cycle and 05/400 are registered trademarks of International Business Machines Corporation. © 1993 IBM Corp. 















with GpiMove and then cause the line 
| segment ab and the curved segment 
) bc to be drawn with GpiPartialirc. The 


——! current drawing position is now ¢; 


we query it to later draw line seg- 
ment de. We then move back to point 
a with GpiMove and draw curved seg- 
ment ad, this time without a line seg- 
ment. (This is done by making the arc 
parameters equal to that of Figure 6 
line segment bc.) Finally, de is drawn 
using c as the end of the segment de. 
The area is then closed, forcing color 
to be rendered inside it. 

This method is repeated for each 
saturation increment up to the last 
increment value which is similar 
except for the fact that its radius is 
the actual radius of the color wheel. 
This is done because rounding error 
may occur when the Saturation incre- 
ments do not divide evenly into 100. 

Figure 10 shows the drawing 
method for the final area. The major 
differerence is that the arc parameters 
are equal to the radius of the color 
wheel and need not be calculated. 

Now that we understand how the 
colors within the wheel are drawn, 
we can begin to explore how to put 
color into a useable control. Before 
we lay out the architecture of the 
final control, however, we will touch 
on the design goals for our color 
wheel. 


DESIGN GOALS 

Why don’t we just use the color 
wheel within the scheme palette pro- 
vided with Presentation Manager? 
Unfortunately, because the color 
wheel is neither a public method 
within the WorkPlace nor a control 
within Presentation Manager, we 
can’t even try to use it within any of 
our applications or WorkPlace 
objects. As Foley et. al. point out, the 
HSV method of describing color is 
also more user friendly, in that the 
user can see and select from available 
colors without needing an under- 
standing of color theory. Therefore, 
our goal is to create a control at least 
as good as, if not better than, the 





GpiCrea -eLoeCo. orTable(hPS 5 UL LCOLF_RGB, ol, OL, (PLONG)NULL) ; 
GpiSetColor(hPS, (LON abc); 

GpiBegindrea(hPS, BA_NOBOUNDARY | BA_ALTERNATE); 

ap.1P = ap.1Q = (1SaturationInc + 1Radius) / 100L; 


GpiSetArcParams(hPS, Bap); 
GpiMove(hPS, &ptlOrigin) ; 
/* Draw the outside arc +/ 
Sine we bptlirsean, MAKEFIXED(1, 0), 
| MAKEFIXED(cAngle, 0), 
MAKEFIXED(LAngle, 0)); 
/* Draw the closure line from the ending point of the inner arc to the 
/* ending point of the outer arc and close the area bracket forcing the 
/* color fill of the area drawn in the saturation color. */ 
GpiLine(hPS, &ptl0rigin) ; 


GpiEndArea(hPS) ; 





Figure 7. Area 1 dra wing method 





Figure 8. Area 2 drawing method 


INITIAL DESIGN INVESTIGATIONS 
When we were first constructing the 
color wheel for a real life application, 


Workplace color wheel. But “better” 
comes with a price, as we will illus- 
trate. 
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Figure 9. Area 2 drawing method 


we found that we could, through prop- 
er design, allow the specification of the 
hue and saturation components so the 
degree of realism that the color wheel 
displayed was greater than that within 
the Workplace Scheme Palette. 

We found that as we set the hue and 
saturation to finer values, it took longer 
and longer to draw the actual color 
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wheel. Now we had to make a choice: 
greater realism or better display speed? 
Table 1 shows times for drawing the 
color wheel based on the hue and satu- 
ration increments. 

As you can see, the finer the incre- 
ments, the longer the drawing time. 
(The timings shown are based on the 
final implementation of the color 


1993 


wheel.) Earlier drawing methods tl 


explored included drawing the colors 
as pie wedges from the origin of the 


wheel to the outside of the circle, 


reducing the radius for each increment. 
This was fine for large increments but 
could be exceedingly slow with incre- 
ments of 1° for hue and 1° for satura- 
tion. We determined that the drawing 
routine would have to be as fast as pos- 
sible and do only necessary drawing. 

We began to see some inherent 
problems when we developed the color 
wheel as a control, mainly due to the 
fact that the environment we were 
using allowed us to treat it like any 
other control in the system, despite the 
amount of time it required. Each time 
the control was resized, or another win- 
dow that overlapped it was removed, 
the system would be tied up while the 
color wheel was redrawn. 

We decided to create the wheel as a 
bitmap in memory to reduce the impact 
on the system once we had rendered 
the image in memory. This way, we 
would have to display the bitmap only 
when an area of it was invalidated. 

Although this solution saved time in 
later stages, time was still a problem 
when the control was first created. 
Since the drawing routine would have 
created the bitmap within a memory 
presentation space of the main thread, 
it retained control of the message 
queue while the image was being con- 
structed. The only way we could deter- 
mine to alleviate the problem was to 
place the drawing within a thread. The 
result was a design that allowed for the 
drawing within a thread, and for that 
drawing to result in a bitmap. 


COLOR WHEEL CONTROL 
ARCHITECTURE 

The resulting control allows for three 
different drawing methods: the wheel 
is constructed in real time, as a bitmap 
image, and as a bitmap image within a 
secondary thread. 

The first method causes the color 
wheel to be redrawn each time the con- 
trol is resized or an area of the wheel is 
invalidated. The second causes the 
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color wheel to be drawn as a bitmap 
image, which is displayed each time an 
area of the wheel is invalidated. (If the 


—! wheel is resized, a new bitmap is creat- 


ed for the new size.) In both cases, 
drawing the color wheel forces a pause 
in the processing of the message queue 
since the routine performs all of the 
drawing before returning control to the 
Presentation Manager. 

In the third method, based on the 
second, the drawing is performed in a 
thread and control is returned to Pre- 
sentation Manager immediately after 
the thread is launched. 

We designed the color wheel with 
the styles listed in Table 2 and allowed 
for a control data structure, as shown 
in Figure 11. Within this structure, we 
allowed the specification of hue and 
saturation increments as well as the 
radius of the circle. 

Instead of describing each of the 
areas of the color wheel window proce- 
dure, we will discuss some areas in 
which we have implemented special 
handling for the bitmap and threading. 


BITMAP CONSTRUCTION 

When creating the bitmap image of 
the control, we create a memory 
device context using DevOpenDC and then 


create a presentation space where the 
image will be drawn using GpiCreatePS 
for that context. Once the bitmap for- 
mat is determined using DevQueryCaps 
and GpiQueryDeviceBitmapFormats (i.e., the 
display type for which the bitmap is 
being constructed), we create the 
bitmap using the GpiCreateBitmap API. 


Figure 10. Area 4 drawing method 


With GpiSetBitmap, we then set the 
bitmap to use in the drawing and draw 
the color wheel. 

Once the wheel is drawn, we free 
the bitmap from the memory device 
context, allowing it to be used within 
our painting routines. We do this by 
making the bitmap handle within the 


)) When creating the bitmap image of the control, 
» we create a memory device context using 
DevOpenDC and then create a presentation 

| space where the image will be drawn using 

) GpiCreatePS for that context. 


GpiSetBitmap call NULL. Finally, we disas- 
sociate the presentation space from the 
device context by specifying a NULL 
value for the device context parameter 
in Gpidssociate, before destroying the 
presentation space using GpiDestroyPS 
and closing the device context with the 
DevCloseDC API. 





THREADING 

In conjunction with the bitmap cre- 
ation, we allow the bitmap to be creat- 
ed within a thread, thus returning con- 
trol to the Presentation Manager. This 
allows the timely creation of all con- 
trols within a window or dialogue. If 
this is not done and hue and saturation 
values increase by small increments, 
when you invoke a dialogue your 
application will appear hung because 
the dialogue is not immediately dis- 
played. Only when the bitmap image 
has been created will the processing for 
the dialogue be complete. 

The threading is very simple, but 
the thread must be coordinated with 
the rest of the control. 

Threading is only used if the control 
is creating a bitmap image of the color 
wheel. The thread is launched from 
two places, the WM_CREATE and WM_SIZE 
messages, and is designed to be 
stopped during the drawing phase 
since a sizing message can be received 
by the control before the bitmap image 
of the color wheel is fully formed. 

When the thread routine is started, 
it issues a WinInitialize call. Although 
this step has never been properly docu- 
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mented in any of the OS/2 toolkits, you 
must issue a WinInitialize call in sec- 
ondary threads in OS/2 Presentation 
Manager applications because it pre- 
pares the thread to use the Wins, Gpit, 
and Dev* API calls. Presentation Manag- 
er records information, such as errors, 
on a per-thread basis through the 
anchor block. 

After the WinInitialize, the routine 
creates a bitmap image of the color 
wheel. Once the image is complete, the 
area where it is to be displayed within 
the control is invalidated with WinInval- 
idateRect. This forces the bitmap image 
to appear for the first time. Finally, the 
thread is terminated using the WinTermi- 
nate and DosExit functions. 


COORDINATION ISSUES 

AND METHODS 

Coordinating the drawing thread with 
the rest of the control initially appears 
to be a job for semaphores. While they 
can be used, a simpler method (which 
has less likelihood of creating a mess 
with deadlocks) can be implemented 
using elements of the internal data 
structure as private signaling mecha- 
nisms. 

We need to determine the 
sequence in which the control is to 
perform its activities. One such activ- 
ity, stopping the thread while it is 


_ A threaded bitmap allows 

| the timely creation of all 

| controls within a window 
or dialogue. 


drawing the bitmap, occurs when the 
window is being resized before 
another drawing request completes. 
This is done with the GpiSetStopDraw 
and GpiQueryStopDraw APIs, specifically 
designed for drawing in threads. 
When we receive the WH_SIZE message, 
we check to see if the style of the con- 


Calculations 


Hue Saturation Time 

10 10 3.85 3,600 
5 5 12.45 7,200 
1 1 256.3 s 36,000 


Table 1. Color wheel drawing times (timed on an IBM Model 70-821, 80486 at 25 MHz) 


Style Purpose 
CWS_BITMAP 
CWS_THREADED 
CWS_AUTOSIZE 
CWS_SOLIDCLR 
CWS_HSB 


CWS_RGB 


Table 2. Color wheel styles 


trol indicates that a bitmap image is 
used to render the color wheel. If this 
is true, we then check to see if the 
bitmap is to be created within a sepa- 
rate thread. If this is also true, we 
then use one of our coordination 
methods, checking to see if the thread 
is active. This can be determined 
because we recorded the thread ID 
within our private control data; in 
addition, we have the coordination 
convention that when a value within 
the thread ID holder is present the 
thread is active and when the value 
is zero the thread is not active. 

If a thread ID is present, we issue 
GpiSetStopDraw for the presentation space 
of the bitmap, with a stop draw condi- 
tion of SDW_ON. Within the drawing rou- 
tine of the color wheel, we check to see 
if the drawing is being done within a 
thread and use GpiQueryStopDraw after 
each hue increment is drawn to see if 
drawing is to terminate. 

Back in sizing processing, after we 
have issued GpiSetStopDraw, the thread is 


Use bitmap to render image of wheel 
Use threading when creating bitmap 
Radius determined by the control 

Use solid colors when rendering 

Color notification is HSB CWN_HSBCLRSELECTED 


Color notification is RGB CWN_RGBCLRSELECTED 


killed with Doskill Thread and a new one 
is launched with DosCreateThread. 

Once the drawing is complete and 
the bitmap image has been created, the 
thread routine clears the thread ID 
holder and then uses WinInvalidateRect to 
force the bitmap image to be displayed 
within the control. 

To make sure that all of this works 
properly, the thread ID holder is again 
used to allow the bitmap image to be 
displayed within the control. When the 
WH_PAINT message is received, the code 
checks to see if the style of the color 
wheel is a threaded bitmap. When it 
determines this to be the case, it next 
checks to see if the thread is active by 
looking for the thread ID within the 
private control data. If it is active, the 
outline of the wheel is drawn with the 
GpiMove and GpiFullérc APIs. If it is no 
longer active, however, the code is 
bypassed and a check is made for the 
bitmap handle. If the handle is present, 
the bitmap is rendered with GpiWCBit- 
Blt. 
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CLIPPING 

You may be wondering what clipping 
has to do with a color wheel and why 
we would want to use it. Quite simply, 
we need to use clipping because we 
never liked doing trig in school! 

Once the color wheel is displayed, it 
is used to select colors. The easiest way 
to implement color selection is to let the 
user move the mouse pointer over the 
desired color and click. But what about 


Figure 12. Crosshair clipping 


informing the user visually of the loca- 
tion after it is selected? This is where 
clipping comes in. 

The best way to depict the location 
is to use an exaggerated crosshair, 
always confined to the wheel, trans- 
versing the circle horizontally and ver- 


tically. There are two ways to create the 
crosshair. One is to calculate intersec- 
tion points on the edge of the circle and 
draw from those points. This method 
tends to be a bit on the slow side since 
we have to use trigonometry to calcu- 
late the points. Also, if any rounding 
off occurs within our calculations, the 








fa typedef struct CLALCDRTA 


| - : ULONG 4 cb; 
LONG Lngle; 
| LONG: SaturationInc; 
| LONG ‘Iadius; 
| } CLRWHLCDATA ; 


b am 


Figure 11. Color wheel control data 


cross will not stop at the intersection 
point of the circle but may fall outside 
or just inside the circle. 

The second creation method 
involves clipping. Here, we describe 
the outline of the circle through Gpi 
APIs and let the Gpi clipping routines 


Clipping is also used to determine if the user has 
clicked the mouse pointer within the color whee! 
circle or Is dragging the crosshair inside It 


clip the cross hair to the circle limits for 
us, even if we start and end the 
crosshair lines outside the limits of the 
circle, as shown in Figure 12. 

To use clipping, we first define the 
characteristics of the circle with 
GpiSetArcParams and start a path with 
GpiBeginPath. After moving to the center 





+f 
+/ 


/* Saturation Increment +*/ 
/* Radius 7 */ 





point of the circle with Gpifove, we draw 
the circle with GpifullArc and close the 
path with GpiEndPath. Having described 
the circle, we invoke clipping to the 
path described by the circle with GpiSet- 
ClipPath. Not that hard from our point 
of view, since all the hard work is done 
by the Gpi APIs. We can now draw the 
crosshairs using the normal GpiMove and 
Gpiline APIs. The starting and ending 
points can be outside the limits of the 
circle, as shown in Figure 12, We draw 
the line and Gpi clips the line segments 
ab and cd, showing only the segment be. 


SELECTION 

Clipping is also used to determine if 
the user has clicked the mouse pointer 
within the color wheel circle or if he or 
she is dragging the crosshair inside it. 
Here, we use clipping to determine if 
the mouse point is within or outside 
the circle. Again, we must describe the 
circle as we did for the crosshairs; 
instead of drawing the crosshairs, how- 
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ever, we check the point where the 
mouse was clicked or moved to with 
GpiPtVisible. If GpiPtVisible returns a TRUE, 
the point is within the circle. If it is 
FALSE, it is outside the circle. 


STILL TO COME 

In a future article, we will show how to 
integrate the color selection control 
with a WorkPlace object. 


Chris Andrew, WordPerfect Corp., 1555 
N. Technology Way, Orem, UT 84057. 
Andrew works in the OS/2 Shared Code 
group at WordPerfect Corp. He previously 
worked for IBM Hursley (U.K.) and IBM 
Boca Raton. He has been involved with 
OS/2 Presentation Manager since the 0S/2 
1.2 release and most recently was a mem- 
ber of the OS/2 Workplace Shell team on 
the 2.0 release. Andrew has an honors 
degree in physics from Imperial College of 
Science and Technology, London. 


Mark A. Benge, /6/ Programming System 
Laboratory, 11000 Regency Pkwy., Cary, NC 
2/512. Benge is a staff programmer who 
Joined IBM in 1989 and has since worked 
on various CUA ‘91 controls for OS/2 2.x and 
CUA Controls Library/2. He now works in 
IBM class library user interface develop- 
ment, where he is involved in the implemen- 
tation of C++ classes for direct manipulation. 
Benge received a B.S. in computer science 
from Western Carolina University. 


Matt Smith, Prominare Inc., 100 Front St. 
E., Toronto, Ont, Canada M5A 1&1. Smith 
is lead architect for the Prominare Develop- 
ment System, an OS/2 2.x advanced GUI 
development environment. He has been 
actively involved with OS/2 since 1988 and 
co-founded Prominare in 1990. Smith has 
a degree in architecture from the University 
of Waterloo. 
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The source code can be downloaded from several electronic sources: 


* In the U.S., call the IBM PCC BBS at (404) 835-6600. The source code for this 
article is in File Area 11 under the name CTRLDES.ZIP. 


¢ In Europe, you can find the source code on the International OS/2 Users 
Group BBS at +44 (0)454 633197 or +44 (0)454 633420. 


¢ On CompuServe, the source code is in LIB13 of the OS2DF2 forum. 
¢ If you have a VM account on an IBM node, you can receive the source 


code with the command REQUEST CLRWHL FROM BANZAI AT 
CARVMS3. 


SEPTEMBER/SOCTOBER 1993 


57 





Not long ago, client/server 
development required massive 
amounts of time, money and 
expertise to combine different 
and complex technologies. 

™ Now Digitalk 

PARTS | PARTS® a rapid 

seem) application 
of =) development 
sa » tool set, lets you 
| easily integrate 
™ your software 

De TL ALK assets into 

client/server applications. 

PARTS is the only object- 
oriented technology that lets 
you leverage your legacy code 
and the knowledge of your 
current staff. 

Only PARTS products let 
you take existing code-written 
in Smalltalk/V, COBOL, C, SQL 
and other languages —and wrap 
it into components or “parts? 
Which can then be virtually 








snapped together visually. The result 


is smooth-running client/server 
applications in a fraction of the 
usual time. For a fraction of the 
usual cost. 

PARTS supports all popular 
SQL databases like Sybase, Oracle 
and DB2. Plus legacy or late mode! 





PARTS. THE CLIENT/SERVER INTEGRATION TOOL. 


Ww” 2 


I 
| 


mu 


- 


systems like CICS, COBOL, APPC 






























































ll 











[yl 


yl 








( 





li 
IM 


- ; 


| 


. 
. 


t 


i 





A 


ca 


i 





F | 














NH 
iT 


Wi 

Mi 

lh 

i, WD 





























and SOM. And PARTS lets you 


develop on both OS/2 and Windows. 


RATED #1 - TWICE. 
Only months ago, PC WEEK 
awarded PARTS Workbench the 
highest rating ever in the OS/2 





till 


am 


category, calling it “the defini- 
tive visual development tool’ 

And IntoWorld ranked 
PARTS the #1 component- 
based tool for visual develop- 
ment. InfoWorld's Stewart 
Alsop adds: “There's nothing 
like it on the PC.” 

To make large teams pro- 
ductive, PARTS also supports 
group development and version 
control. Plus PARTS has a host 
of graphical power tools to give 
you all the power of objects - 
without the learning curve. 

10 YEARS EXPERIENCE. 

And PARTS is from 
Digitalk, The company that’s 
been providing object-oriented 
tools to the Fortune 500 longer 
than anyone else in the world- 
with over 125,000 users. 

Call 800-531-2344 X 606 
and ask about our 
PARTS Workbench | 
Evaluation Kit. 

With minimum 
effort, you'll learn why 
PARTS is the maximum 
solution for client/server 
integration. 


DIGITALK 




















The IBM Graphics Interface Kit/2 helps programmers develop intelligent graphical interfaces for applications. 


This article explores the main concepts of GIK/2 and explains how to use the product to develop an application 
interface. BY ROLAND HATSCHKA and SILVIA HANSJAKOB 


Graphics Interface Kit/2: 
Visualizing and 
Manipulating Data 


esigning and implementing intelligent 

graphical interfaces is a complex task 

requiring a substantial investment of time, 
money, and skilled personnel. Changing require- 
ments during development can necessitate signifi- 
cant changes to an application’s interface. Graph- 
ics Interface Kit/2 lets developers quickly produce 
and modify intelligent graphics interfaces, making 
it easier to reallocate valuable resources and 
reduce development time. 

Graphics Interface Kit/2 (GIK/2) minimizes the 
amount of code that must be written to prototype 
and develop intelligent graphical interfaces for 
applications. GIK/2’s customizable, intuitive inter- 
face and easy-to-use design tool let developers cre- 
ate prototypes of interfaces in one or two hours. 
The product can also generate the C source code 
needed to link the interface with the application 
code. A library of almost 300 high-level functions 
helps developers further refine interface behavior, 
and a set of layout algorithms allows automatic 
positioning of the objects on the screen. 


CONCEPTS 

There are two classes of symbols in GIK/2, nodes 
and links. GIK/2 interprets displayed symbols as a 
network diagram. The symbols, used to map user 
actions to application functions, are manipulated 
to access and change application data. 


Nodes. Nodes usually represent data objects (for 
example, airplanes or people, as shown in Figure 1, 
or processes or data stores). Each node in a window 
can be independently positioned and manipulated. 
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Links, Links usually represent relationships (for 
example, wires, business reporting lines, data 
flows, or control flows, as shown in Figure 2, or 
wires or business reporting lines). They are con- 
nected to nodes or other links and are affected by 
actions performed on them. 

GIK/2 provides a WYSIWYG editor for creat- 
ing symbols. Symbols can have more than one part 
so as to reflect changes to underlying application 
data. For each symbol part, you can specify: 


¢ What the symbol part looks like 

¢ What happens when a user clicks on the sym- 
bol part 

¢ Which application data or functions are rep- 
resented by the symbol part. 


At least one form must be defined for each 
symbol. While semantic variants for a symbol can 
be shown by defining more than one form, the 
code used to manipulate the symbol needn't be 
changed. To show the state of a symbol, multiple 
shapes can be defined for each form. For example, 
you may want to specify a specific shape when a 
symbol is dragged across the window. For each 
form, up to four shapes can be defined to deter- 
mine a symbol’s look in the following locations 
and states: 


e In the main window (standard shape) 

¢ In the palette (palette shape) 

¢ While being dragged (drag shape) 

¢ While being attached to another symbol 
(attachment shape). 
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Figure 1. Airline reservations system built with Graphics Interface Kit/2 


DEVELOPMENT OVERVIEW 

The development process consists of 
several steps. You first prototype an 
interface using the GIK/2 design tool, 
an interactive tool with a WYSIWYG 
drawing facility that can be used by 


nonprogrammers. The prototype is 
then saved in a design file that can be 
repeatedly tested, refined, and extend- 
ed. Initially, the prototype need contain 
only an application-specific symbol set 
and a palette from which instances of 
the symbols can be dragged. 


When the prototype is satisfactory, 
it is time to write customizing code 
(C/C++ functions). The code links the 
interface with the application data and 
implements any special menu choices 
created for users. 


GIK/2 minimizes the code that must be 
written to prototype and develop intelligent 
graphical interfaces for applications. 


GIK/2 supports these programming 
tasks in two ways. First, it generates 
source code for the developer’s cus- 
tomizing code. Second, GIK/2’s library 
of about 300 high-level functions can be 
called from either the customizing code 
or the application main code. 
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Help for users is typically the last 
development step. Here, GIK/2 pro- 
vides a library of generic help panels 
that can be edited to describe the 
unique features of an interface. 


THE GRAPHICS EDITOR 

The graphics editor can be thought of 
as a generic interface; a set of windows, 
menus, and supporting features often 
needed in a graphical interface. At run 
time, this generic interface can be 
dynamically modified by: 


e The design file, which populates 
the interface with symbols 

e The customizing code, which syn- 
chronizes the interface with the 
application and implements any 
special menu choices that have 
been created 

e The help library, which provides 
users with context-sensitive infor- 
mation. 
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Customer orders 


All manipulation of the symbols, 
such as selection, creation, and dele- 
tion, is done in the main window of the 
graphics editor. In addition, the graph- 
ics editor supports the following win- 


dows, all of which can be customized 
with the design tool: 


¢ Palette window (for adding sym- 
bols) 

* Overview window (for scrolling 
and zooming) 

* Color window (for changing the 


Figure 2 Data flow diagram editor built with Graphics Interface Kit/2 


Reorder 


color of symbols) 

* Clipboard view window (for dis- 
playing the contents of the clip- 
board). 


The graphics editor contains approximately 50 
standard actions that users might need to build 
or manipulate a graphical interface. 


GENERIC ACTIONS 

The graphics editor contains approxi- 
mately 50 standard actions that users 
might need to build or manipulate a 
graphical interface. Called generic 
actions because they can be modified to 
suit a specific interface, these actions 
are split into implicit actions, invoked 
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Write inventory report 


directly with the mouse, and explicit 
actions, invoked from the menu bar. 

Implicit generic actions include 
moving symbols, symbol parts, and 
bend points; attaching links to symbols; 
sizing nodes; adding a bend point to a 
link; selecting symbols or symbol parts; 
and scrolling and zooming the main 
window from the overview window. 
Explicit generic actions include adding, 
deleting, copying, and changing the Z- 
order of symbols; opening, saving, and 
printing the graphics; and applying a 
layout algorithm. 


EVENTS 
The graphics editor can detect the 
occurrence of nearly 50 events, such as 
the selection, addition, movement, or 
deletion of a symbol, the display of a 
pull-down menu, or the click of a 
mouse button. 

An event is an opportunity to spec- 
ify special processing. You can tell the 
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graphics editor to call an event han- 
dler (C/C++ function) whenever a 
particular event occurs. Any special 
processing is defined in the event han- 
dler. 


GRAPHICS LIBRARY FUNCTIONS 
Graphics Interface Kit/2 offers a library 
of about 300 high-level functions that 
can be called to modify the default 
behavior of GIK/2 while an event is 
being processed, to connect graphical 
objects to application data, and to open 
and close GIK/2 windows from the 
application main code. For example, 
there are functions for: 


¢ Initializing and quitting GIK/2 
windows 

¢ Inserting and removing choices in 
the menu bar 

¢ Opening, zooming, printing, and 
saving the main window 

¢ Linking application data to the 
main window 

* Retrieving and displaying help 
panels 

* Creating and deleting symbols 

¢ Changing symbol sizes, text labels, 
and the position of symbols 

* Setting a flag indicating that a sym- 
bol or symbol part should be affect- 
ed by a later action 

* Retrieving symbol information 
(position, size, overlap) 

¢ Linking application data to sym- 
bols 

* Selecting a layout control and 
selecting its parameters. 


CUSTOMIZATION WITH C-CODE 

After developers have specified a 
design, they can add customizing code 
to build a running application. The cus- 
tomizing code will add the application 
logic and link the application data to 


LAN Layout 


Radial Layout 


Horizontal Tree 


Vertical Tree 


Ellipse 


This layout arranges all nodes connected directly or 
indirectly to a central site. This algorithm arranges root 
nodes in a circle and the other nodes as trees growing 
from these nodes. 


This layout arranges nodes as a set of recursive circles. 
The nodes are clustered in a circular shape. 


This layout arranges nodes as a horizontal tree. The 
roots are at the top and the leaves are at the bottom. 


This layout arranges nodes as a vertical tree. The roots 
are at the left and the leaves are at the right. 


This layout arranges nodes in a single ellipse. The 
algorithm repositions the nodes in the order of 
occurrence. 


Table 1. Layout algorithms available with Graphics Interface Kit/2 
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the graphical interface. Figure 3. Network topology drawn with the LAN Configurator example 


EVENT HANDLERS 

Events and event handlers are the key 
link between the interface graphics and 
the application data. Event handlers 
must be registered in the design tool, 
which then generates code templates 
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for them. The collection of event and 
action handling functions, called cus- 
tomizing code, resides in an OS/2 
dynamic link library. 

Event handlers can be used for 
many purposes, such as: 


1993 


¢ Map graphical editing actions to 
modifications of the underlying 
application data represented by the 
graphical objects. For example, 
when a user deletes a link in the 
diagram, a relationship in a server 


database may be deleted. i ee ee Le ee ee ee ee SS ae 
¢ Associate §application-defined Symbol types PC 
behavior with user actions. For PRINTER 
+ a example, when a user clicks with LINK 


mouse button 2 on a specific sym- 
bol, a dialogue for data entry may 


be displayed. Parts for PC PC_SYMBOL 
* Modify the behavior of the graphics NETWORK_NAME (textual symbol part) 
editor. For example, users could be SERVER (initially invisible) 
prohibited from moving a specific 
symbol outside a defined areainthe Parts for PRINTER PRINTER_SYMBOL 
diagram. PRINTER_NAME (textual symbol part) 
NETWORK_PRINTER (initially invisible) 
ACTION HANDLER 
With the action handler, you can sup- 
ply application-specific actions that — Forms for PC PC_FORM 
users can select from the menu bar. For 
these application-specific functions, use Forms for PRINTER LASER_PRINTER 
the action handler, a C function called MATRIX_PRINTER 
when a user selects a menu choice asso- 
ciated with it. It contains a large switch Forms for LINK LINK_FORM 


statement, with one case for each appli- 
cation-specific menu choice. Each 


choice has a unique identifier associat- Table 2. Symbol structure of the LAN Configurator example 


ed with it. TE eee 
|*------------------------------ won en tenn nnn nnn nnn enna nnn nena === - = / 

DEVELOPING AN APPLICATION /* INCLUDE RELATED DEFINES */ 

In this example we build a LAN con- [RRQ eeeeeeeeeeeeeeeeeeeneeneenee ae Fore ee ee ee 

figurator, shown in Figure 3, that helps 

system administrators document the define INCL_DDS /* 0S/2 definitions +/ 

computers and printers in a network. #define INCL_PM /*/PW! definitions +/ 

Building the configurator can be bro- 

ken down into six main tasks: a re RySS). 2) ha eee RN oe a */ 
/* HEADER FILES +/ 

Defining Symbol Types. Using the design Qi UN greens ici +/ 

tool, create a symbol type and define its 

structure. This is done by entering gi ncaude <os2.h> /* 0S/2 header file / 

names that identify the symbol type | gsi aide <evyga.h> /* GIK/2 header file */ 

and its parts and forms, as shown in #include "LANCONE.H" js. Cabayited hadar 421k 

Table 1. No additional parts to the pre- 

defined LINK.B0DY are defined for the | CRM ee Ree ate ie eRe Me Ee eS OF 

aie /* LOCAL FUNCTION PROTOTYPES +/ 
[ #------------------ 2-9 nnn nnn nnn nnn nn nn nnn nnn nnn nnn nn nnn nnn nnn nena nn= +/ 


Drawing the Symbol Shapes. When creat- 
ing the graphics for a symbol, associate 
one or more graphical elements with 
each symbol part. A symbol part, which 
can be composed of bitmaps, icons, 


SHORT GSENTRY MyActionHandler (DHND,USHORT,MPARAM,MPARAM) ; 


/ EEAEKAAKAE KEARSE LAKES EAA SES ERE SE EEE EEES ESE EEE RES EREL EERE EEL EL ERE SESE / 


pointers, polylines, ellipses, boxes, and A er eee 
arcs, will contain different graphical ele- Ie Pp +/ 
ments for different forms of a symbol wenn, Det 

: /* — DHND dhnd (I): Diagram handle. +/ 


type, allowing you to build complex 

symbols. The symbol shapes are drawn 

with an interactive WYSIWYG editor. _ Figure 4. The action handler changing selected printer symbols to network printer symbols 
(Automatically generated code lines are printed in bold text.) (continued on page 65) 
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Defining a Symbol Palette. In the design 
tool, specify the number of rows and 
columns in the palette, then associate a 
symbol form with each cell of the 
palette. 


Testing the Design. At this point, the test 
action can be used for the first time. 
You get a full-function graphics editor 
in which graphical symbols can be 
added, deleted, or manipulated, but 
there is no connection to the applica- 
tion data. 


Specifying the Layout Control. The name 
of the layout control can be one of the 
GIK/2-provided controls or a self-writ- 
ten control. Menu choices added to the 
menu bar enable users to lay out the 
diagram. Table 2 shows layout algo- 
rithms available with GIK/2. 


Writing Customizing Code. The C-code 
used to customize the default behavior 
of the generic editor must be contained 
in a DLL whose name is specified in 
the design tool. 

You can add special processing to 
the generic editor by defining either an 
action handler or an event handler. 

An action handler is invoked when 
a user selects a choice from the menu 
bar. In this example, a menu choice 
turns all selected printer symbols into 
network-printer symbols. To achieve 
this, add a menu choice to the default 
menu bar, register the C function MyAc- 
tionHandler as an action handler, gener- 
ate the skeleton code, and add the spe- 
cific code to the skeleton, as shown in 
Figure 4. 

An event handler is invoked when 
GIK/2 detects one of the predefined 
events. In this example, the graphics 
editor is customized so that a requester 
symbol is changed to a server symbol 
when a user double-clicks on it. To 
achieve this, register the C function 
MyDoubleClick to the event EV_DOUBLE_CLICK, 
generate the skeleton code, and add the 
specific code to the skeleton, as shown 
in Figure 5. 

The following files can be generated 
by the design tool to support the devel- 
opment of customizing code: 


/* USHORT menu_id (I): Action selected by user. +/ 
/+  MPARAM = mparamt. (I): PM-data. s/ 
/* PARAM mparam2 (I): PM-data. +/ 
/+ */ 
/+* Returns: +/ 
/* — GS_OK +/ 
/* +/ 
/* Description: +/ 
/* The function handles all non-generic actions. +/ 


/ HAAR HARERA RAIA EERARE EEA EEREAE REAR EEE EA TR AEREREA ERE EREREAAEE EERE RERS / 


SHORT GSENTRY MyActionHandler(DHND dhnd, 
USHORT menu_id, 
MPARAM mparami , 
MPARAM mparam2) 


{ 
SHND shnd; 
SHORT sym_type; 


/* symbol handle */ 
/* symbol type 


+/ 


Figure 4. [he action handler changing selected printer symbols to network printer symbols. 
(Automatically generated code lines are printed in bold text.) (continued on page 66) 
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You need to do two things: 

Go on-line with CompuServe 
Information Service. Use Golden 
CommPass to do it. 


CompuServe hosts 0S/2 developer 
and user forums monitored by 
technical personnel. IBM devel- 
opers are there with responses 
to anything that’s got you 
stuck. Other OS/2 pro- 
grammers and enthu- 
siasts are there. too, 
comparing notes and 
giving feedback. It's 
definitely the place to be. 
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Looking for fast answers 
to your development questions? 










ie To ompuServe: 
#600230 1000 | Ore) @ Corl eine 
(609) sarees CommDass” | porch ieee 


CompuServe’ 





Time is money when you connect to 
CompuServe, and Golden CommPass 
Saves you both. |t lets you compose 
your questions off-line, send them in 

ad flash and disconnect. It gets your 
replies while you're busy program- 
ming. It's a native OS/2 app, with all 
the power and features you'd expect. 


Get the fastest access to 
answers. Golden CommPass 
keeps your development 
schedule on course. The 
fact is, the sooner you start 
using our program, the sooner 
they'll be talking about yours! 









Leress Soll ware 





ware distributors. You can also 
ah ee | 





fax to 43-1-21145-4490, Attn: 
GIK/2. | 


The program is also available in 
French, German, Italian, and 
Japanese.The following IBM docu- 


Graphics Interface Kit/2 Getting 
Started (IBM Doc. SH19-8189) 


Build Intelligent Graphics With 
G511-1785) 


Include file—Defines the constants 
for the symbol type and other 
design characteristics. 

Action handler—C file containing 
the skeleton code for handling 
application-defined menu choices. 
Event handler—C file containing 
the function skeletons for all regis- 
tered events. 

Definition file—Defines the cus- 
tomizing code DLL. 

Make file—Creates the customizing 
code DLL. 








Figure 4. The action handler changing selected printer symbols to network printer symbols 7 
(Automatically generated code lines are printed in bold text) (continued from page 65) 


5 The event handler changing requester symbol to a server symbol when a 
double-click occurs (Automatically generated code lines are printed in bold text) - 
(continued on page 68) 
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Figure 5. The event handler changing a requester symbol to a server symbol when a 
double-click occurs (Automatically generated code lines are printed in bold text) 
(continued from page 66) 
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in a Dos, Win-OS2 or OS/2 session 


running under OS/2 2.1, now you have the 
mm = ability to send and receive faxes - without 4 e \ } = 
leaving the application. Just select the Fax/PM driver 


as your printer. To fax...just print! 














Fax/PM 32-bit also really capitalizes on the 
advanced features of the Workplace Shell 
object-oriented interface. You can send 
faxes right from the Workplace Shell by 
simply dragging and dropping a data 
object to the fax object. 

Features like these are too good to keep 
to yourself, so there are also Fax/PM versions 
available for LAN and Client-Server 
environments, all CID enabled. 

And applications developers will 
appreciate SOM APIs that allow for integration of the 
Fax/PM engine into custom applications. We could 
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0S/2 Presentation Manger 








resentation Manager (PM), the primary 

application environment under OS/2, 

deals with menus, dialogue boxes, and 
scroll bars accessible through either the keyboard 
or mouse. It allows applications to share a video 
display, mouse, and printer with other applica- 
tions in a fixed windowing environment. PM pro- 
vides three major features: an object-oriented pro- 
gramming environment, consistent user interface, 
and device independence. 

Presentation Manager provides an object-ori- 
ented, message-based programming environment. 
In the object-oriented approach, an object consists 
of data and a set of rules that describe how to 


PM applications are object-oriented, 
message-based, CUA-conforming, 
and device-independent. 


manipulate the data. The Presentation Manager 
implementation of the object consists of a window 
and a procedure. The window is manipulated by 
invoking the procedure by sending a message to 
the window. Messages can originate from the user 
(mouse or keyboard), from the PM timer, or from 
other PM applications. For instance, a window can 
be closed or minimized by a message event gener- 
ated by a mouse click. 





provides an environment to develop object-oriented and device-independent applica- 
tions with consistent graphical user interfaces. This article describes the major features, components, and inner 
workings of Presentation Manager. BY PYLEE LENNIL 


Demystifying the OS/2 


Presentation Manager 


One of PM’s goals is to provide capabilities for 
creating applications that conform to the Common 
User Access (CUA) guidelines of the IBM Systems 
Application Architecture (SAA). The goal of SAA 
is to provide a consistent, easy-to-use user inter- 
face across IBM system applications. Conforming 
to SAA guidelines significantly reduces the learn- 
ing curve for new applications and also minimizes 
the effort required to port the applications to other 
CUA systems. Presentation Manager CUA sup- 
port provides capabilities such as menus, dialogue 
boxes, and scroll bars that can be used to generate 
applications that conform to CUA. 

PM’s environment makes applications device- 
independent; applications need not be aware of 
the characteristics of a specific device such as a dis- 
play, printer, or plotter. Applications that access 
devices using the PM API automatically become 
device-independent and will run on many devices, 
provided that PM supports a driver for them. 


STRUCTURE OF PRESENTATION MANAGER 
PM consists of a window manager, graphics sub- 
system, and input and event manager, shown in 
Figure 1, These form an extension of OS/2 that 
provides window management, graphics support, 
and input and event support. Application window 
management is provided by the window manager 
and graphics support by the graphics subsystem. 
The input and event manager manages input 
events from the mouse, keyboard, and system 
timer. The following section examines these com- 
ponents in detail. 
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PM Applications 


Window Manager 


Input and Event 
Manager 


Mouse, Keyboard 
Timer 


Figure 1. Presentation Manager structure 


Window Manager. The window manager, which 
manages application windows and message 
queues, contains a set of window functions and 
application message queues, as shown in Figure 2. 
An application issues PM window function (WIN) 
calls to invoke these functions. A window receives 
input in the form of messages and displays out- 
put to a device through presentation space. Mes- 
sages, which can originate from the mouse, key- 
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GPI 


Graphics Subsystem 


Graphics Interface 


Functions 


Graphics Engine 


Presentation 
Drivers 


Display, Printer, 
Plotter 





board, system timer, or other applications, are 
used to manipulate windows. 

An application creates a window with the Win- 
CreateWindow function. Applications can create many 
windows, each used for a dialogue between the 
application and user. A window can be moved, 
minimized, or maximized with input from the 
user. Data in a window can also be moved or 
copied from one window to another or between 


rss3 








areas of the same window using the 
Presentation Manager clipboard func- 
tions (cut, copy, and paste). Presenta- 
| tion Manager provides several types of 
windows to support CUA guidelines: 


¢ Desktop window—The parent of 
all applications’ main windows, 
the desktop window shows the 
entire screen when it is used by 
PM in a windowing environ- 
ment. 


¢ Main Window—The first win- 
dow created by an application, 
the main window contains the 
title of the application in the title 
bar and a list of program func- 
tions in the action bar. 


* Child Window—A child win- 
dow is created by the main win- 
dow within its boundaries to 
display additional information. 
A parent window can have one 
or more child windows. 


¢ Dialogue Window—A special 
type of child window mainly 
used to communicate with the 
user, the dialogue window con- 
tains controls such as entry 
fields and list boxes. 


¢ Message Window—The mes- 
sage window displays messages 
to the user. 


The window with which a user is 
interacting, or the active window, 
receives keyboard or mouse input. 
Each window has a class that associates 
it with a window procedure, which 
defines the behavior of windows in the 


System Queue 


Mouse Keyboard 


Figure 2. Window Manager structure 


class. There are two types of window 
classes: public and private. The win- 
dow procedures for public classes, 


Each window has a unique handle, obtained 
when it is created. With it, applications can send 
messages to a destination window using the 
WinSendMessage or WinPostMessage functions. 


which can be used by any PM applica- 
tion, reside in dynamic link libraries. 
Private classes, however, are available 
only to the application that created 
them. Using the WinRegisterClass func- 
tion, the application registers a window 





class during application initialization; 
this associates the class with a window 
procedure. The application can then 
invoke the window procedure by dis- 
patching a message. 

Presentation Manager’s object-ori- 
ented programming environment is 
implemented in the window manager. 
The window is the object; a window 
procedure is associated with a window 
class. The window is manipulated by 
sending messages to invoke specific 
functions in the window procedure 
that change window behavior. Each 
window has a unique handle, obtained 
when it is created. With the handle, 
applications can send messages to a 
destination window using the Win- 
SendMessage or WinPostMessage functions. 
Messages from the mouse, keyboard, 
and system timer are stored in system 
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cae queue. PM applications can retrieve 


a ) /* main caus */ these messages with WinGetMsg and send 
{ to the window procedure with WinDis- 
WinInitialize(); /* initialize application  +*/ patchMsg. 
WinCreatetsgQ aue(); /* create application queue +/ Messages. ca is the peery 
way that PM manipulates windows. 
WinRegisterClass(); /* register window procedure +*/ Messages S originate from the mouse, 
/* to the window class */ keeboard, PM timer application, or 
operating system. A mouse message 1s 
WinCreateStdWindow() /* create main vindov +/ generated by mouse movement or by 
clicking the mouse button; a keyboard 
/* message processing loop */ message 1s generated for every key 
vhile( WinGetMsg()); Tago peseige tro qudiés. +/ stroke. A timer message is generated 


when a PM timer has elapsed. Appli- 
cation messages are sent by an applica- 
tion to other application windows. A 
mouse or keyboard message has the 
following structure: 


WinDispatchMsg();  /* dispatch message to */ 
} /* window proc +/ 


Figure 3. Application main procedure 
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* Window handle 
* Message ID 

} © Parameter 1 

* Parameter 2 


* Time - 


¢ Pointer data. ~~ 





The window handle identifies the 
destination application window, while 
the message ID identifies the message 
type. For instance, an ID of 7a hex iden- 
tifies a keyboard message (WM_CHAR) and 
71 hex identifies that mouse button 1 is 
down (W4_BUTTON1DOWN). Parameters 1 and 
2 contain information depending on the 
message type. For instance, a keyboard 
message Parameter 1 and 2 in a key- 
board message contain scan code, con- 
trol code, and other information from Figure 4, Application window procedure 
the pressed key. Time fields contain the 
time that a message was sent and the 
pointer data contains the position of the 
mouse pointer when the message was 
sent. 





PRESENTATION MANAGER 


Message Queves. PM maintains two 
types of message queues, a system 
queue and an application queue. (See 
Figure 2.) The system queue, created 
during PM’s initialization time, is used 
to store mouse and keyboard messages. 
Messages are removed from the system 
queue in a first in, first out order, 
ensuring the same sequence as the user 
input. Timer messages are not stored in 
the system queue because they are 
processed immediately to update the 
timers set by the applications. 

An application queue, created for 
every application and its associated 
application threads with WinCreateMs- 
gQueue, receives messages from other i 
applications. Messages are sent Figure 5. Input and event manager structure 
between applications with WinSendMes- 
sage or WinPostMessage, retrieved by ¢* Creates an application queue with WinGetMsg and WinDispatchMsg 








WinGetMsg, and dispatched to the win- WinCreateMsgQueue to read messages from queues and 
dow procedure with WinDispatchisg. dispatch them to the window pro- 
The application that processes the ° Registers the window procedure in cedure shown in Figure 4. 
messages consists of a main procedure Figure 4 to the window class with 
and a window procedure. The main WinRegisterWindowClass Message processing is initiated 
procedure, shown in Figure 3, performs when the application issues a WinGetMsg 
several tasks: * Creates an application main win- function, as shown in Figure 3. The 
dow using WinCreateStdWindow function scans the system queue for 
¢ Initializes PM facilities for the messages specific to the application. If a 
application with WinInitialize * Performs message looping using message is found, it returns it to the 
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application’s main procedure. The 
main procedure, in turn, dispatches the 
message to the window procedure with 
WinDispatchMsg. Next, WinGetNsg scans the 
application queue for any messages 
specific to the application. When one is 
found, it retrieves and dispatches it to 
the window procedure with WinDis- 
patchMsg. 

The window procedure consists 
mainly of a multiple selection switch 
statement with a case for each message, 
as shown in Figure 4. The switch state- 
ment selects appropriate routines to 
manipulate the window. All nonrele- 
vant messages are handled by a default 
window procedure, WinDefWindowProc, 
which ignores the message. The control 
is then returned to the main procedure, 
which continues scanning for more 
messages in the message queues. 


Input and Event Manager. The input and 
event manager processes input events 
from the mouse, keyboard, and timer. 
As shown in Figure 5, input events are 
routed to PM through the kernel device 
driver PMDD.SYS. The mouse and key- 
board events are processed by the sys- 
tem queue handler, while the timer tick 
is processed by the timer handler. The 
mouse event data consists of informa- 
tion such as coordinates of the current 
mouse position; the keyboard event 
consists of scan code and control code. 
The system queue handler converts the 
mouse and keyboard event data into 
message packets and stores them in the 
system queue. A timer event is generat- 
ed for every timer tick and the timer 
handler updates the timer data struc- 
ture set up by the PM applications. If 
any timer has elapsed, it sends the mes- 
sage WM_TIMER to the appropriate appli- 
cation queue, Applications issue a 
WingetMsg function to retrieve messages 
from the system queue or a WinPeekMsg 
to examine the messages. The messages 
are then dispatched to the window pro- 
cedure with a WinDispatchNsg function 
call. 


Graphics Subsystem. The graphics sub- 
system allows the application to create, 
display, and retrieve graphics, text, and 
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pictures in a device-independent man- 
ner. The subsystem consists of a graph- 
ics program interface (GPI), graphics 
engine (GRE), and presentation drivers, 
illustrated in Figure 6. 

The GPI programming interface 
consists of a set of GPI functions that 
create, manipulate, and display graph- 
ics objects such as lines, arcs, and char- 
acter fonts. GPI functions call the 
graphics engine to manage output. 


PRESENTATION SPACE 

An application must create a presenta- 
tion space to manage graphics it creates 
before it can draw ona device. The pre- 
sentation space is a data area main- 
tained by the presentation manager. 
The application writes graphics attrib- 
utes such as color or line style and 
transforms them to the presentation 
space. These device-independent 
graphics attributes are translated to 
device-dependent data by the device 
context before being sent to a device. 
The application must therefore associ- 
ate the presentation space with a con- 
text-specific device before data can be 
written to that device. 

There are two types of presentation 
spaces: normal and micro. The type of 
presentation space chosen by an appli- 
cation is determined by the type of 
drawing. 


Normal Presentation Space. Normal pre- 
sentation space is used by applications 
that use graphics segments or retained- 
drawing functions to generate complex 
pictures. A graphic segment is a collec- 


PM's graphics subsystem lets your application 
create, display, and retrieve text and graphics. 


tion of graphics, drawings, and 
attribute commands stored in the pre- 
sentation space. The major advantage 
of using normal presentation space is 
that the application can use the space 
to write to devices such as video dis- 
plays, printers, and plotters. Created 
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during program initialization and tl 


destroyed during program termination 
time, normal presentation space 
requires a large amount of memory 
and is intended to be used by an appli- 
cation for long periods of time. Normal 
presentation space also has slower per- 
formance. 


Micro Presentation Space. Micro presen- 
tation space is normally used to gener- 
ate simple drawings. There are two 





Figure 6. Graphics subsystem structure 


types of micro presentation space: nor- 
mal and cached. 

Although normal micro presenta- 
tion space can be used to write to mul- 
tiple devices, the application must use a 
separate presentation for each device. 
It requires less memory space and pro- 
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vides better performance. Normal pre- 
sentation space is used for short peri- 
ods of time and destroyed after per- 
forming a drawing task. Its major dis- 
advantage is that it does not support 
graphics segmentation and GPI seg- 
ment functions. Normal micro presen- 
tation space is created with GpiCreatePS 
and destroyed with GpilestroyPS. 
Cached micro presentation space is 
used only by the window manager to 
display a window on a video display. 
Always associated with a video dis- 
play, it cannot be used to draw on 
other devices such as a printer or plot- 
ter. The application opens a cached 


micro presentation space using WinOpen- 
WindowDC. 


DEVICE CONTEXT 

Device context describes the character- 
istics of display devices such as the 
video display, printer, and plotter. The 
device context structure describes a 
physical device and conveys this infor- 
mation to the presentation space associ- 
ated with it. It then translates device- 
independent graphics to device-depen- 
dent drawings. A window device 
context is opened with WinOpenWindowDC 
and a nonwindow device context with 
DevOpenDC. Each open call creates an 





Figure 7. Graphics engine and presentation driver 


instance of a device context, which is 
destroyed when the application closes 
it with DevCloseDC. The steps needed to 
use presentation space and the device 
context to write graphics data on a 
device are: 


1. Open device context 

2. Create presentation space 

3. Associate presentation space with 
device context 

4. Draw text and graphics to presenta- 
tion space 

5. Destroy presentation space. 


GRAPHICS ENGINE 

The primary functions of the graphics 
engine are to provide graphic simula- 
tion and manage graphics output to 
display drivers. These functions, which 
can be accessed with the PM GRE func- 
tion calls, are available to display dri- 
vers through a function dispatch table 
maintained by the graphics engine. (See 
Figure 7.) The table, which contains 
entry points to the functions, is shared 
by the graphics engine and display dri- 
vers. The graphics engine passes a copy 
of the dispatch table to each presenta- 
tion driver when it is loaded. The pre- 
sentation driver, in turn, fills the table 
with its own function entry points. 


PRESENTATION DRIVERS 

The presentation driver is a higher- 
level interface to display, printer, and 
plotter devices. Unlike kernel device 
drivers that reside in ring 0, the presen- 
tation driver resides in ring 2 or ring 3. 
It provides graphics functions for dis- 
play and printer devices; these func- 
tions are accessed through a presenta- 
tion driver interface (PDI). Presentation 
drivers’ I/O privileges allow them to 
access the devices directly. Complex 
graphics functions that cannot be 
implemented by the presentation dri- 
vers are implemented by the graphics 
engine. These functions can be directly 
called from the presentation driver 
using a dispatch table mechanism, as 
shown in Figure 7, When a device con- 
text is initialized, the dispatch table is 
passed to the presentation driver by the 
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graphics engine. There are two types of 
presentation drivers, the display driver 
and the hardcopy driver. 


Presentation Display Driver. The main 
function of the presentation display 
driver is to display graphics data on 
video display devices. The driver must 
execute quickly to update the display 
screen, writing directly to the video 
screen using the I/O privilege. The dis- 
play driver can call kernel display 
device drivers to obtain display 
adapter hardware and video memory 
buffer addresses. It calls the graphics 
engine for complex graphics functions 
not implemented in the display driver. 
The presentation display driver is 
loaded and initialized when the presen- 
tation manager is initialized. The dis- 
play driver is also used by the mouse 
driver through POINTDD.SYS to draw 
the mouse pointer on the screen. 


Presentation Hardcopy Driver. The hard- 
copy driver draws graphics on printers 
and plotters. It supports different 
forms, provides a dialogue for user 
configuration, and calls kernel drivers 
to simulate certain functions. Printer 
drivers call the graphics engine to sup- 
port complex graphics functions. 
Unlike the display driver, the hardcopy 
driver is loaded not during PM initial- 
ization but when the application issues 
a DevOpenDC command to open the print- 
er device context. 


HOOKS 

Presentation Manager provides a hook 
mechanism that allows applications to 
monitor and modify the message 
stream. Hooks can be installed in the 
system or application queue; installing 
them into the system queue affects all 
applications, while the individual 
application queue affects only the 
queue’s owner. Hooks are installed 
with WinSetHook and released with WinRe- 
leaseHook. The name of the hook proce- 
dure and the type of hook is specified 
with the WinSetHook function. Hooks can 
be categorized into six types: 


1. Input—The input hook monitors 


the system queue. Used to monitor 
event data from the mouse and 
keyboard, it is called with WinGetMsg 
or WinPeekMsg. 


2. Send-Message—The send-message 
hook monitors messages not post- 
ed to a queue. Using input and 


send-message hooks, an application |f J 


can monitor all window messages. 


. Filter—The filter hook provides 


input message filtering during the 
application’s main procedure mes- 
sage loop. This allows applications 
to examine or modify the message 
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before dispatching it to the window 
procedure. 


4. Journal-Record—This hook moni- 
tors the system queue and allows 
the application to record input 
events. For example, it can be 
used to record a set of mouse and 
keyboard events and played back 
later using the journal-playback 
hook. 


5. Journal-Playback—This hook is 
used to play back a set of mouse 
and keyboard events previously 
recorded with the journal-record 
hook. 


6. Help—The help hook is used while 
processing the WM_HELP message. 


TIMER SUPPORT 

The PM Timer facility allows an appli- 
cation to set a timer with a specific 
duration. The application starts the 
timer with WinStartTimer. PM maintains 
a linked list of timer entries updated at 
each timer tick by the input and event 
manager, If any of the timer entries is 
empty, it sends a WM_TIMER message to 
the corresponding application queue. 
The application retrieves the message 
during the next WinGetMsg function and 
dispatches it to the window procedure, 
which in turn invokes a timer handler. 
The application can stop the timer with 
WinStopTimer. 


DATA EXCHANGE 
Presentation Manager provides two 
mechanisms to exchange data between 
applications, the clipboard and dynam- 
ic data exchange (DDE). 

The clipboard is more commonly 


used but less flexible. The user invokes 
the clipboard using the cut, copy, or 
paste commands to transfer data within 
an application or from one application 
to the another. The only restriction on 
the clipboard is that data must be in a 
format that can be understood by the 
destination application. The application 
accesses the clipboard through a set of 
WIN functions; for example, an appli- 
cation issues a WinOpenClip function to 


Presentation Manager provides two mechanisms 
to exchange data between applications, the 
clipboard and dynamic data exchange. 


open the clipboard. 

DDE is a data exchange facility that 
allows PM applications to exchange 
data using shared memory. Unlike the 
clipboard, DDE provides a one-time 
data exchange with user intervention, 
allowing continuous data exchange 
between server and client applications 
without any user intervention. Normal- 
ly, the client initiates the data exchange 
by requesting data from the server, 
which responds by providing data to 
the client. An application can reside on 
both client and server and a client can 
request data from multiple servers; for 
example, a client application can 
request data from a server application 
and then act as a server by forwarding 
the data to another client. 

Presentation Manager provides 
three functions to support DDE. A 
client initiates the data exchange using 
the WinDdeInitiate function. The server 
responds to the request using WinDdeRe- 
spond. The WinDdePostMsg function allows 
an application to post a message to 
another application with which it is 
carrying out a DDE. 


ACCELERATOR TABLE 
An accelerator is a keystroke that gen- 
erates a command message for an 


application. This mechanism can be 
used for activating a menu item by typ- 
ing the keystroke. This is done by fil- 
tering the keyboard input and translat- 
ing the keystroke to a corresponding 
command before reaching the applica- 
tion. For instance, to generate help mes- 
sages, you can set up an accelerator 
(Alt-F8) to generate the WM_HELP message 
that invokes the application window 
procedure. The accelerators are kept in 
an accelerator table. Accelerators can be 
associated with the system queue or 
there can be one for each application 
window. 

The system queue accelerator table 
affects all applications, while the indi- 
vidual window accelerator table affects 
only that application window. An 
application can modify both its own 
accelerator table and the system accel- 
erator table. An application creates an 
accelerator table using the resource-def- 
inition file, which contains accelerator 
definitions that interact with a standard 
window when the window is created. 


ATOM TABLES 

Presentation Manager provides a 
mechanism for converting a character 
string into a 16-bit unique word. Each 
word, called an atom, has a unique ID 
and an associated counter, used to keep 
track of atom use. An atom table con- 
tains a collection of atoms and is main- 
tained by the atom manager. When the 
counter becomes zero, the atom is 
deleted from the table. Using an atom 
instead of a string has many advan- 
tages. A string used in many data struc- 
tures can be replaced by its atom and 
saves memory space. Searching an 
atom takes less time than searching a 
string. Atoms can be used for creating 
system-wide unique strings for win- 
dow messages or DDE formats used 
between applications. 

The atom table is maintained by a 
set of PM functions, WinCreateAtomTable 
creates an atom table, WinkddAtom adds an 
atom to the table, WinFinddtom finds an 
atom, and WinDeleteAtom deletes an atom 
from the table. 
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MMPM/2 provides not only multimedia device control but also easy-to-program animated buttons, sliders, and 
secondary windows. BY DONALD G. JOHNSTON 


Programming the Graphical 
User Interface Extensions of 
MMPM /2 





Donald Ec Johnston 


revious articles on MMPM/2 have covered 
the Media Control Interface, which allows 
high-level programs to work with multi- 
media devices with a minimal amount of pro- 
gramming. This article covers another major addi- 
tion provided by MMPM/2, the addition of sec- 
ondary windows, graphical push buttons 
(two-state and animated), and circular sliders. 
These build on the home entertainment system 
paradigm and help reduce the user’s learning 
curve when faced with new multimedia applica- 
tions. The stop, pause, play, and volume controls 
that people are used to on stereos will now appear 
on the computer screen. 





OPERATING THE WINDOW 
When a user clicks on the Play push button, 
shown in Figure 1, it appears to depress into the 


|) MMPM/2 GUI Support [ENE] 


fog hole 





Figure 1. A secondary fifncouk 


screen, beep, and then start animating; the three- 
dimensional effect and the animation are handled 
by MMPM/2, while the beep and the notification 
to start animation are part of the program covered 
in this article. Clicking on the Stop push button 
causes the same three-dimensional effect, triggers 
a beep of a different tone, and stops the animation 
of the Play push button. 

An important point of the MMPM/2 support 
for these graphical controls is the extension to the 
normal keyboard control that is possible with PM 
objects. Pushing the Tab key jumps focus between 
the two groups defined (the Stop and Play push 
buttons make up the first group, and the circular 
slider the second). When you tab to the first group, 
the Stop push button is highlighted; use the left or 
right cursor control key to change the highlight to 
the Play button. When the Enter key is pressed, 
the highlighted push button appeares to be 


- pressed. 


While the Play button is animating, you can 
control the animation rate with the circular slider. 
There are several ways to control the circular slider: 


1. Tab to the Volume control and use the left and 
right cursor control keys, or click on the -/+ 
icons at either end of the slider range. The set 
value should change by increments of 1. 

2. Click on one of the tick marks at the outside of 
the slider. The set value (and the pointer) will 
jump to that value. 

3. Press and hold the Mouse Select button while 
the mouse pointer is inside the circular slider. 
The slider will track the mouse pointer as you 
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move it around the screen. The set value will 
increase by increments of 10 at most, or enough 
to catch the mouse. 


This program also has a default size item in the 
system menu. If the window has been resized, it 
can be returned to its original dimensions by click- 
ing on this item, part of the secondary window 
support provided by MMPM/2. 


THE TEMPLATE FOR THE 
SECONDARY WINDOW 
The dialogue box definition file (MMPMGUI.DLG), 
shown in Figure 2, defines the layout (or template) 
of the dialogue box used as the secondary win- 
dow. It is defined as a dialogue box template by 
the keyword DLGTEMPLATE. 

The #define statements ensure that the correct 
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sections of the secondary window header file (SW.H 
from the MMPM Toolkit/2) are used to compile 
this resource. 

The DIALOG statement defines the window. The 
text data MMPM/2 GUI Support appears in the title bar. 
The various styles (FS_) and flags (FCF_) define the 
layout of the window, delineating a sizing border, 
a system menu, and so on. 

The CONTROL statement (defining either a WC_GRAPH- 
ICBUTTON or a WC_CIRCULARSLIDER) is used to add 
graphic controls to the dialogue box. The graphic 
buttons can be either two-state (Stop) or animated 
(Play). 

The CTLDATA statement defines the control data 
associated with the push buttons and defines the 
bitmap or bitmaps, such as ID_BMP_STOP and 
TD_BMP_PLAYn, that are to be used. The constants used 
in this definition are defined in the MMPMGUI.H file, 
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shown in Figure 3, which is included a ES! 





with the DLGINCLUDE command. [EE EEE 
) * 4 
CONNECTING THE BITMAPS * File: MMPMGUI.DLG + 
TO THE CONTROLS ¥ + 


The resource compiler file MMPMGUI.RC, 
shown in Figure 4, is used by the 
resource compiler to draw together all 
resources used by the MMPMGUI.DLG pro- 
gram. RCINCLUDE includes, as one of the 
resources, the dialogue box definition 
file in Figure 2. 

The BITMAP statements define the file 
used for each symbolic reference (for 
example, STOP.BMP is used for ID_BMP_- 
STOP). These bitmaps can be copied from 
the DUETi sample code subdirectory that 
comes with the MMPM Toolkit/2. 

The STRINGTABLE statement is used to 


EEEEEEEEEEEEAE EERE / 


#define INCL_CIRCULARSLIDER 
#define INCL_GRAPHICBUTTON 


#include <sw.h> 
DLGINCLUDE 1 "mmpmgui.h" 


DLGTEMPLATE ID_DLG_MAIN LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 
DIALOG "MMPM/2 GUI Support", ID_DLG_MAIN, 12, 6, 148, 84, 
NOT FS_DLGBORDER | FS_SIZEBORDER | WS_VISIBLE, 
FCF_SYSMENU | FCF_TITLEBAR | FCF_MINBUTTON | 


define all character strings used. Each 
string (“Default Size) has an [ID number 
(IDS_DEFAULTSIZE) associated with it. The 
tilde (~) marks the character to be 
underlined. The ID number IDS_DEFAULT- 
SIZE is defined in the MMPMGUI.H file as 1. 


DEFINING THE PROGRAM 
STRUCTURE 

The C compiler uses the definition file 
MMPMGUL.DEF, shown in Figure 5, to 
get information about the type of pro- 
gram it is about to compile. 

The NAME parameter defines this as a 
PM program (WINDOWAPI) with the name 
MMPMGUI. The DESCRIPTION text MMPM/2 GUI 
Support ends up in the header of the exe- 
cutable file. The program has one entry 
point (NainProc), used by the OS/2 oper- 
ating system to direct messages meant 
for it. 

For all MMPM/2 programs the 
STACKSIZE should be at least 16,000 bytes. 


PROGRAMMING FOR A 
SECONDARY WINDOW 
It is now the responsibility of your C 
program to first ask MMPM/2 to create 
the secondary window and then con- 
trol various parameters of the graphic 
controls and receive messages from the 
window. Support code that does this is 
shown in Figure 6. 

As # include <os2.h> and #define 
INCL_WIN are used in standard PM pro- 
grams, we use #include <os2me.h> and 


"", ID_GPB_STOP, 28, 60, 23, 14, 


WS_GROUP | WS_TABSTOP | WS_VISIBLE 
CTLDATA GB_RESOURCE, "", 1, ID_BMP_STOP 


"", ID_GPB_PLAY, 85, 60, 40, 14, 


CTLDATA GB_RESOURCE, "", 5, ID_BMP_PLAYO, 
TD_BMP_PLAY1, ID_BMP_PLAY2, 
ID_BMP_PLAY3, ID_BMP_PLAY4 


"Volume", ID_SL_VOLUME, 33, 0, 85, 58, 


WS_GROUP | WS_TABSTOP | WS_VISIBLE 


FCF_MAXBUTTON 
BEGIN 
WC_GRAPHICBUTTON, 
CONTROL 
WC_GRAPHICBUTTON, 
GBS_ANIMATION | WS_VISIBLE 
CONTROL 
WC_CIRCULARSLIDER, 
END 


END 
Figure 2. The dialogue box template 


fidefine INCL_SW to include all secondary 
window support provided by 
MMPM /2. 

The secondary window defined in 
the dialogue template file is created 
when the WinLoadSecondaryWindow() func- 
tion is used (instead of the WinCreateStd- 
Window() used in PM programs). This 
window still needs the normal anchor 
block (hab) and message queue (hmq) 


used to receive messages. To create the 
Default Size item in the system menu, 
MMPM/2 provides the WinInsertDefault- 
Size() function. 

Before control is returned from the 
WinLoadSecondaryWindow() function, a 
WH_INITDLG message is sent to the dia- 
logue procedure of the program Main- 
Proc(). When this message is received, 
the animation rate of the Play push but- 
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Figure 3. The program's header file 


Figure 4. The resource compiler file 
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Figure 5. The definition file 


ton is set with a GBM_SETANIMATIONRATE 
message. The parameter 100 indicates 
that the bitmap is to be changed every 
100 milliseconds (1/,) second). For the 
circular slider, the range (0-100), incre- 
ment value (10), and initial value (80) 
can be set with the messages 
CSM_SETRANGE,  CSM_SETINCREMENT, and 
CSM_SETVALUE. 

Watch for whenever your program 
sends a CSM_SETVALUE message to the cir- 
cular slider. The slider will, in turn, 
send a CSN_CHANGED message back to the 
window’s dialogue procedure; your 
program should be ready to handle 
this. 

When a user clicks on the Play push 
button, MMPM/2 creates the three- 
dimensional effect of the button push- 
ing into the screen and then sends a 
WH_COMMAND message to MainProc(). (The 
first parameter, ID_GPB_PLAY, defines 
which button caused the message.) The 
program sends a GBM_ANIMATE message, 
with the TRUE parameter, back to the 
button to start it animating. MMPM/2 
will then use the five bitmaps defined 
in MMPMGUI.DLG, cycling through them 
every 100 milliseconds to give the 
appearance of movement. 

Clicking on the Stop push button 
as that for the Play button and a WM_COM- 
MAND message with the ID_GPB_STOP button 
identified. A GBM_ANIMATE message with 
the FALSE parameter is then sent to the 
Play push button to stop its animation. 

The DosBeep() function provides user 
feedback and adds a little excitement to 
the program. It also delays the return 
to MMPM/2, which shows that the 


graphic buttons remain down while the 
“i program processes a message. The 





pushes the button in, sends the pro- 
gram a synchronous message, then 
pops the button out. 

Graphics buttons under MMPM/2 
also send WH_CONTROL messages to the 
dialogue procedure. This is the best 
way to handle messages from the cir- 
cular slider. All the effects of this slider 
are created by MMPM/2, and the pro- 
gram needs only handle the CSN_CHANGED 
and CSN_TRACKING parameters of the 
WH_CONTROL message received from the 
ID_SL_VOLUME control. CSN_TRACKING is sent 
for each increment as MMPM/2 tracks 
the mouse. CSN_CHANGED is sent to provide 
the program with the final value set 
from any user action on the slider. Nor- 
mally these would be used to control 
the volume of a multimedia device, but 
here they just control the animation 
rate of the Play push button. 

All messages not explicitly handled 
by this program are passed on to 
WinDefSecondaryWindowProc(), MMPM/2’s 
default secondary window procedure. 
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+ * 
* File: MMPMGUI.C +# 
* + 


esses | 


#define INCL_WIN 
#define INCL_SW 


#include <os2.h> 

#include <os2me.h> 

#include "mmpmgui.h" 

/* Procedure Prototype */ 

MRESULT EXPENTRY MainProc(HWND hwnd, 
ULONG msg, MPARAM mpi, MPARAM mp2); 


/* Global Variables */ 


HAB_ hab; 
HMQ = hing; 
QMSG = qmsg; 


HWND = hwndFrame, hwndPlay, hwndCirc; 
INT main( VOID ) 
{ 

CHAR szDefaultSize[30]; 


hab = WinInitialize( 0); | 

hmq = WinCreateMsgQueue( hab, 0); 

hundFrame = WinLoadSecondaryWindow(HWND_DESKTOP, HWND_DESKTOP, 
MainProc, (HMODULE) NULL, ID_DLG_MAIN, NULL); 


WinLoadString( hab, (HMODULE) NULL, IDS_DEFAULTSIZE, 
sizeof (szDefaultSize), szDefaultSize); 
WinInsertDefaultSize(hwndFrame, szDefaultSize) ; 


while ( WinGetMsg( hab, &qmsg, (HWND) NULL, 0, 0) ) 
WinDispatchMsg( hab, &qmsg ); 


WinDestroySecondaryWindow( hwndFrame ); 
WinDestroyMsgQueue( hmq ); 
WinTerminate( hab ); 

return( 0); 


[FERRER ERAEEAEEEREEERERERS 
* Main Dialog Procedure + 
HERERERAEEEREEEEREEEEEEES / 


MRESULT EXPENTRY MainProc(HWND hwnd, ULONG msg, MPARAM mp1, MPARAM mp2) 
{ 

switch( msg) 

{ 


case WM_INITDLG: 
hwndPlay = WinWindowFromID( hwnd, ID_GPB_PLAY); 


WinSendMsg (hwndPlay, GBM_SETANIMATIONRATE, 
MPFROMLONG(100L), NULL); 


Figure 6. The C support code (continued on page 85) 
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Figure 6. The C support code (continued from page 84) 
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OS/2 device drivers must handle address conversion in cases where the operating system cannot do so. Using 
an application and device driver DevIoctl example, this article demonstrates how to determine when address 
conversion is necessary and how to convert real to virtual addresses. BY FRANK J. SCHROEDER 


Converting Real Addresses to 
Virtual Addresses in OS /2 2.x 





Frank J. Schroeder 





ne obstacle OS/2 1.x device drivers may 
need to overcome when running under 
the virtual memory environment of 
OS/2 2.x is how to correctly convert a DOS 
application’s real memory pointer, passed in the 
command or data packets on a DevI0Ct1 API, to 
its virtual equivalent. This article explains why 
the operating system does not convert embed- 
ded pointers for the device driver. It provides a 
device-driver example demonstrating how to 
do the address conversion, as well as DOS and 
OS/2 16-bit application code showing how 
applications pass embedded pointers on DevI0Ct1 
calls. The OS/2 device driver's DevI0Ct1 routine 
shows the necessary calculations to convert an 
embedded pointer prior to accessing an appli- 





cation’s buffer. This article assumes the reader 
has general knowledge of 8086 assembly lan- 
guage and OS/2 device drivers. 


INTRODUCTION 
The DOS and OS/2 operating systems provide 
an API called device input/output control 


(DevI0Ct1) that enables applications to commu- 
nicate with device drivers. Every device driver 
provides unique functions to control its device; 
usually these functions set a device-specific fea- 
ture or return the current device-specific fea- 
ture setting. Each device driver defines the 
functions it supports, the parameters needed to 
perform the functions, and, within the confines 
of the DevI0Ctl API, how the parameters are 
passed to the device driver. 

A DOS application, when started in a DOS 
session of the OS/2 2.x operating system, exe- 
cutes in the Virtual 86 (V86) mode of the Intel 
processor. The Intel processor in V86 mode 
uses a segment and offset value to directly 
address physical memory. The segment and 


Since an OS/2 device driver executes in protected mode, any real 
address must be converted to its appropriate virtual address prior 
to accessing the data at that location. 


offset address is also referred to as a real 
address. An OS/2 application, when started in 
an OS/2 session of the OS/2 2.x operating sys- 
tem, executes in the protected mode of the Intel 
processor. The Intel processor in protected 
mode uses a selector and offset value to trans- 
late the address to physical memory. The selec- 
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tor and offset address is also referred to as a 
virtual address. 

A DOS application, when executing in V86 
mode, passes a real address on API calls to the 
operating system. Since an OS/2 device driver 
executes in protected mode, any real address 
must be converted to its appropriate virtual 
address prior to accessing the data at that loca- 
tion. 


Devi0Ctl API 

The DevI0Ctl API defines a set of parameters 
that can be customized to each device driver. 
The parameters passed by a DOS application 
through the DOS version of the DevI0Ct1l API 
(int 21h, AH=44h) are identical to the set of para- 
meters passed by 16-bit OS/2 applications 
through the OS/2 version of the DevI0Ctl API 
(DosDevI0Ct1). The category-code parameter is a 
numeric value that categorizes the type of 
device driver being called (such as parallel 
port, serial port, mouse, or disk). The function- 
code parameter is a numeric value that defines 
the function the device driver is requested to 
perform. A set of reserved, operating-system- 
specific category and function codes are 
defined in Appendix C of the DOS 5.0 Technical 
Reference and chapter 18 of the OS/2 2.0 Physical 
Device Driver Reference. (See the References sec- 
tion for details.) 

In addition to the category- and function- 
code parameters, the DevI0Ctl API defines two 
parameters (the command and data packets) 
that pass function-specific parameters to the 
device driver. The addresses of the command 
and data packets are passed to the device dri- 
ver on the DevI0Ctl API. If the command and 
data packet pointers are V86 mode addresses, 
the operating system converts these addresses 
to their appropriate virtual addresses prior to 
calling the device driver. 

The command and data packets contain 
parameters in a format predefined by the 
device driver. If a device driver defines an 
embedded pointer as a parameter passed in the 
command or data packet, this far pointer can- 
not be converted by the operating system into 
its virtual address, because the application and 
the device driver are the only ones that under- 
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stand the format of these packets. It is the 
device driver’s responsibility to determine 
whether the process calling the device driver is 
a V86 mode process and convert the embedded 
pointer to its appropriate virtual address, so the 
device driver can complete the requested func- 
tion. 

DOS applications that use the DOS protect- 
ed-mode interface (DPMI) must convert their 
embedded pointers to the segment and offset 
format prior to issuing a DevI0Ctl API. The OS/2 
device driver treats DPMI applications as DOS 
applications, assumes the embedded pointer is 
a real address, and tries to convert it accord- 
ingly. If the DPMI application passes a protect- 


v86Mode STRUC 

v86_off dw 

v86_seg dw ? ; 
v86_len dw ? ; 
v86Mode ENDS 

datapkt db SIZE v86Mode DUP (0) __; 

cmdpkt db 0 ; 

buffer db "PARMS_GO_HERE" ; buffer 
BUFLEN EQU $ - buffer : 


Figure 1. DevIOCt1 data structures 


; setup ioctl parameters 


lea bx ,datapkt 

mov ax,OFFSET buffer 
mov [bx]. v86_off ,ax 

mov [bx] .v86_seg,ds 

mov [bx] .v86_len,BUFLEN 


Figure 2. DevIOCt1 data packet initialization 


ed-mode address, the device driver performs 
the address conversion when it should not. 
The 16-bit OS/2 DevI0Ct12 API and the 32-bit 
OS/2 DevI0Ctl API also pass, as parameters, the 
lengths of the command and data packets and 
the addresses of these variables, so that the 
device driver can update the length of the com- 
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; v86Mode Address Offset 
v86Mode Address Segment 
v86Mode Buffer Length 


devioctl buffer - data packet 
devioctl buffer - cmd packet 


size of buffer 


; ds:bx -> data packet 
; get buffer offset 

; save buffer offset 

; save buffer segment 
; save buffer length 
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mand and data packets returned to 
the application. A device driver must 
be at least level-two to receive the 
command and data packet lengths. 
The device-driver level is specified 
within the device-driver header 
found at offset 0 of the device dri- 
ver’s first data segment. The exam- 
ple described in this article uses 16- 
bit instructions and the 16-bit version 
of the DevI0Ctl API, so it does not use 
the command and data packet length 
parameters. 


OPEN AND CLOSE REQUESTS 
Before issuing a DevI0Ct1 request, the 
DOS or OS/2 application must first 
issue an Open request to the device 
driver. The Open API assigns and 
returns a handle parameter to the 
application that must be passed on 
subsequent requests to the device 
driver. The handle is used by the 
operating system as a method of 
retrieving and storing information to 
its data structure regarding commu- 
nication with the device driver. The 
final step to terminate communica- 
tion with device drivers is issuing a 
Close API to free the entry in the 
operating-system data _ structure. 
Because the open and close proce- 
dures vary according to the device 
being opened, they are not shown 
here. 


DevlOCtl DATA STRUCTURES 

The DOS and OS/2 application must 
allocate command and data-packet 
storage to be used when passing 
information to the device driver, as 
shown in Figure 1. The command 
packet is not used for parameter 
passing in this example and conse- 
quently contains only a null (00h) 
byte. The amount of data-packet 
storage and the format of the data 
packet are defined by the V86Mode 
structure. The data packet allocates 
storage for a segment or selector 
(V86_seg) and an offset (V86_off) to 
address a separate buffer containing 
the parameters being passed to the 
device driver. The data packet also 


a 
; issue ioctl request | 


mov ah, 44h ; ioctl function call 

mov al,0Ch ; handle based call 

mov dx ,bx ; ds:dx -> data packet 

mov bx ,handLe ; handle 

mov ch, 80h ; category code - user type 
mov cl,40h ; function code - send data 
mov s1,ds 

lea di, cmdpkt ; Si:di -> cmd packet 

int 21h ; call device driver 

je error ; jmp if error 


Figure 3. DevI0Ct1 from a DOS application 


; Issue ioctl request 


push = ds 

lea dx ,datapkt ; data packet 

push = dx 

push = ds 

lea dx ,cmdpkt ; command packet 

push = dx 

push = 40h ; function code - send data 
push = 80h ; category code - user type 
push _ handle ; handle 

call  DosDevI0Ctl ; call device driver 

or ax ,ax ; jmp if error 

Jnz error 


Figure 4. DevI0Ct1 from an OS/2 application 
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DSEG SEGMENT PUBLIC “data” 


; Generic IOCtl Request Packet Structure Definition 


ReqPacket STRUC 

RPLength db ? ; Request Packet Length 
RPUnitCode db ? ; Request Packet Unit Code 
RPCommand db ? ; Request Packet Command Code 
RPStatus dw ? ; Request Packet Return Status 
RPReserved dd ? ; Request Packet Reserved 
RPQueue dd ? ; Request Packet Queue Linkage 
Category db ? ; Category Code 

Function db ? ; Function Code 

GI0ParmPack dd ? ; PTR to Parm Packet 
GI0DataPack dd ? : PTR To Data Packet 

GIOSFN dw ? ; System File Number 


Figure 5. Device driver real-to-virtual address conversion routine 
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contains storage for the length of the 
separate buffer being passed to the 
device driver (V86_len). Called buffer, 
it contains the string PARMS_ GO_HERE. 


Devi0Ctl DATA PACKET 
INITIALIZATION 

Next, the application initializes the 
parameters being passed within the 
data packet of the DevI0Ctl API to the 
device driver, as shown in Figure 2. 
This code is identical, regardless of 
whether the application is a DOS 
(real or V86 mode) or an OS/2 (pro- 
tected-mode) application. The offset 
portion of the address of the buffer is 
stored in the data packet, followed 
by the segment portion (real-mode 
application) or selector portion (pro- 
tect-mode application) of the buffer 
address, and, finally, the length of 
the buffer. The DS register contains 
the mode-specific application data 
segment or selector value initialized 
by the operating system before the 
application begins execution. 

The category code selected (80h) 
corresponds to the first category 
code not reserved for operating-sys- 
tem use. The function code chosen 
(40h) corresponds to the first function 
code available to send data to the 
device driver. The category and 
function codes selected for use in 
this example are somewhat arbitrary; 
however, they do comply with the 
rules for using these parameters 
defined within the OS/2 2.0 Physical 
Device Driver Reference. No reference 
to restricted use of these parameters 
could be found within the DOS 5.0 
Technical Reference manual. 


CALLING DeviOCtl FROM 

A DOS APPLICATION 
Parameter-passing to the DOS ver- 
sion of the DevI0Ctl API is accom- 
plished by loading the general-pur- 
pose registers with the required 
parameters and issuing an interrupt 
2ih instruction to call the device dri- 
ver to perform the function, as in 
Figure 3. The handle, category code, 
function code, and command and 


data packet addresses are loaded 
into the appropriate registers prior to 
issuing the request. The command 
and data packet addresses are in the 
V86 mode format and are converted 
automatically by the operating sys- 
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GIOParmLen dw ? ; Parm Packet Length 
GIODataLen dw ? ; Data Packet Length 
ReqPacket ENDS 


the AX register. The DOS DevI0Cctl 
parameter-passing convention can 
be found in Appendix C of the DOS 
5.0 Technical Reference. 





CALLING DeviOCtl FROM ; RPStatus Return Codes 


AN 0S/2 APPLICATION 

Parameter-passing to the OS/2 ver- 
sion of the DevI0Ctl API is accom- 
plished by pushing the required 
parameters onto the stack and call- 
ing the device driver to perform the 


REQDONE EQU 0100h 
ERROR_INVALID_PARAMETER EQU 8113h 


; REQUEST IS DONE, NO ERROR, NO RET CODE 
; REQUEST IS DONE, ERROR, RETURN CODE 


; Convert’s Generic INCt1] Data Packet Structure Definition 


sakes as - | vB6Mode STRUC 

function, a8 shown in eapure bets v86_off dw ? ; v86Mode Address Offset 
handle, category code, function code, 186_seg du ? ; vB6Mode Address Segment 
and command and data packet | \g6 44, 4 ? ; v86Mode Buffer Length 
addresses are pushed onto the stack y86Mode ENDS 


prior to issuing the dynamic-link 
call. The command and data packet 
addresses are already in their virtual 
format and do not need to be further 


; Device Helper Function Codes 


DevHlp_VerifyAccess EQU 39 ; 27 Verify access to memory 
Devilp_AllocGDTSelector EQU 45 ; 2D Allocate GDT selectors 
DevHlp_GetDOSVar EQU 36 ; 24 Return pointer to DOS variable 
Deviilp_FreeGDTSelector EQU 83 ; 53 Free allocated GODT selectors 
DevHlp_LinToGDTSelector EQU 92 ; 5C Convert linear address to virtual 


Access to an applications 
aata at interrupt time 
requires a GUT selector. 


; Local Info Segment Structure Definition 


LocalInfoSegmnt STRUC 


processed before being passed to the 
device driver. If an error occurs dur- 
ing the attempt to process the 
DevI0Ctl request, the request returns 
with an error code in the AX register. 
If the AX register contains 0, then no 
error occurred. The OS/? DevI0Ctl 
parameter-passing convention can 
be found in the OS/2 2.0 Control Pro- 
gram Programming Reference. 


DEVICE DRIVER DeviOCtl REQUEST 

PACKET 

The operating system copies the 
parameters that are either in the gen- 
eral-purpose registers or on the stack 
into a request-packet control block 
that is passed to the device driver. 
The request-packet address is passed 
to the device driver in the ES and Bk 
registers, and the device driver is 
called at its strategy entry point to 
process the request. The device dri- 
ver validates the parameters and 


LTS_CurProcID OW ? : Current Process ID 
LIS_ParProcID OW ? - Parent Process ID 

LIS_CurThrdPri DW ? Current Thread Priority 
LIS_CurThrdID DW ? ; Current Thread ID 

LTS CurSessID DW ? ; Current Session ID 
LIS_ProcStatus 0B ? ; Process Status 

LIS_reservedi 0B ? ; Reserved 

LIS_FgndProc OW ? ; Current Process in Foreground 
LTS_ProcType DB ¢ ; Type of Process 

LTS reserved? 0B ? ; Reserved 

LTS _EnvironSel DW ? ; Environment Selector 
LIS_CommandLine DW ? ; Command Line Offset 

LIS_DSeglen DW ? ; Length in Bytes of Data Segment 
LIS StackSize OW ? ; STACKSIZE in Bytes of .EXE file 
LIS_HeapSize DW ? ; HEAPSIZE in Bytes of .EXE file 
LTS ModHandle OW ? ; Module Handle of the Application 
LIS_DSegHan = =s-dODW ? ; Data Segment Handle of Application 


LocalInfoSegmnt ENDS 


; Local Info Segment ProcType Definitions 


LIS_PT_FULLSCRN EQU 0 
LIS_PT_REALMODE EQU = 1 
LIS_PT_VIOWIN EQU 2 
LIS_PT_PRESMGR EQU 3 


Figure 5. Device driver real-to-virtual address conversion routine (continued on page 91) 
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LIS_PT_DETACHED EQU - 


; Local Info Segment Address 


LIS_Addr STRUC 

LIS_Addr_Off DW ? ; Local Info Segment Offset 
LIS Addr_Sel DW ? ; Local Info Segment Selector 
LIS_Addr ENDS 


; Misc Parameters needed for Device Helper Services 


LOCINFOSEG EQU 2 
RACCESS EQU 0 
GDTALLOCATED §=EQU 


; System Local Info Segment - GetDOSVar 
; Read Access - VerifyAccess 
; Flag Equates 


* Global Data Area 


PUBLIC device_help 


device_help dd 0 ; Device Helper Services Pointer 
localinfoseg dd 0 ; Local Info Segment Pointer 
regpkt dd 0 ; Request Packet Pointer 

gdtsel dw 0 ; GDT Selector 

flags dw 0 ; Error Processing Flags 

DSEG ENDS 

CSEG SEGMENT PUBLIC “code” 


ASSUME CS: CSEG,DS:DSEG,ES: NOTHING SS: NOTHING 


; ROUTINE NAME: Convert. Converts V86 address to GDT selector. 


i 


; FUNCTION: The convert routine converts a V86 address (segment: 
' offset) passed in a buffer within a Generic I0Ctl 
API call into a GDT selector that the device driver 
can use to access this memory at task or interrupt 
: time. 

; 

; NOTE: 0S/2 kernel cannot convert an imbedded pointer 

; because it does not know about them. 

: 

; ENTRY: es:bx -> to Generic IOCt1 request packet 

; ds our data segment 

; 

; EXIT: all other registers are not preserved 


PUBLIC convert 
convert proc near 

and flags ,NOT GDTALLOCATED ; set flag off 
mov WORD PTR reqpkt, bx 
mov WORD PTR reqpkt+2,es 


; save req pkt offset 
; save req pkt selector 


; GET POINTER TO LOCAL INFO SEG 


Figure 5. Device driver real-to-virtual address conversion routine (continued on page 92) 
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calls the appropriate device-driver 
routine to service the DevI0Ct1 request 
specified by the function-code para- 
meter. 

The operating system provides 
services to device drivers through 
the device helper (DevHlp) entry point. 
The DevHlp entry-point address is 
passed to the device driver when the 
device driver is called to initialize. 
The DevHlp address must be saved by 
the device driver for future use. Prior 
to calling a DevHlp entry point, a 
device driver loads the DL register 
with the DevHlp function to be per- 
formed and the general-purpose reg- 
isters with any required parameters. 
If an error occurs during the process- 
ing of a DevHlp request, the carry flag 
is set, and the AX register returns the 
error code. 

Each DevHlp service is available to a 
device driver only during certain 
times. Initialization, task, and inter- 
rupt are the three time periods when 
a device driver can execute and 
when these DevHlp services may be 
available. Initialization time occurs 
when the device driver is called to 
initialize itself. Task time is the peri- 
od when the device driver services 
requests entered through its strategy 
entry point. Interrupt time occurs 
when the device driver is called at its 
hardware-interrupt entry point to 
service its device. 

Selector addresses found in the 
local descriptor table are not avail- 
able to device drivers at interrupt 
time. If a device driver needs to 
access an application’s data area at 
interrupt time, the data area must be 
addressed by a GDT selector found 
in the global descriptor table, the 
application must be in context (fore- 
ground), and the device driver needs 
to lock the application’s data area 
into memory. The application does 
not need to be in context if the 
address is made HVDM relative. To 
be made HVDM relative, the handle 
to the VDM must be added to the 
linear address. The device driver 
uses the DevHlp lock service to lock 
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the data area and the corresponding 
DevHlp unlock service to unlock it 
once access is complete. The lock 
request should be issued after the 
device driver verifies access to the seg- 
ment and prior to blocking the applica- 
tion’s thread. The DevHlp VMLock ser- 
vice can be used if the application’s 
data area must be physically contigu- 
ous or within the first 16 MB of memo- 
ry. An alternative is to copy the data at 
task time from the application's data 
area to the device 
driver’s data seg- 
ment; however, this 
approach has perfor- 
mance implications. 
Obviously, O5/2 
device drivers have 
access to their data 
segments at inter- 
rupt time. 





let 





It 1s the 
responsibility 
of the device 
ariver to 
convert any 
embedded 
adaress ina 
command or 
aata packet 
to its virtual 
adaress. 


DETECTING A V86 
MODE PROCESS 
The operating sys- 
tem converts the 
DevI0Ctl command 
and data packet 
addresses to their 
virtual addresses, 
but it does not 
know about any 
embedded address- 
es stored within the 
command and data 
packets. It is the 
responsibility of the 
device driver to 
convert any embed- 
ded address in a 
command or data packet to its virtu- 
al address. If the device driver fails 
to convert the V86 address or con- 
verts it incorrectly, the device driver 
may attempt to access the memory 
by loading a segment register with a 
V86 address while the processor is in 
protected mode. (The Intel processor 
is in protected mode when running 
an OS/2 device driver and the 
processor does an address transla- 
tion on the contents of the segment 
register.) If a V86 address is stored 


mov al,LOCINFOSEG 
mov dl, DevHlp_GetD0SVar 
call DWORD PTR [device_help] 
jnc  —s convert1 
Jmp error 

convertl: 
mov es, ax 
mov ax,es: [bx] .LIS_Addr_Off 
mov WORD PTR localinfoseg ax 
mov ax, es: [bx] .LIS_Addr_Sel 
mov § WORD PTR localinfoseg+2,ax 
les _— bx, localinfoseg 


; get local infoseg addr 
; get dos var function 
; call device help 


; Save infoseg addr 
’ error, exit 


; es:bx -> infoseg addr 
; get infoseg offset 

; Save infoseg offset 

; get infoseg selector 
; Save infoseg selector 
; es:bx -> localinfoseg 


; DETERMINE IF V86 MODE PROCESS (AND CONSEQUENTLY A V86 MODE ADDRESS) 


cmp es:[bx].LIS_ProcType,LIS_PT_REALMODE ; if not v86mode 
; process then 
' no conversion 


Jjne verify 


; ALLOCATE A GDT SELECTOR 


push = ds 

oP. 

lea = di, gdtsel 

mov cx,1 

mov dl, Devilp_AllocGDTSelector 
call  DWORD PTR [device_help] 
jc error 


or flags , GDTALLOCATED 


; CONVERT V86 ADDRESS TO LINEAR ADDRESS 


.386¢ 
les bx, reqpkt 
les bx, es: [bx] .G10DataPack 
movzx  edx,WORD PTR es:[bx].v86_seg 
shl edx ,4 
movzx eax,WORD PTR es:[bx].v86_off 
add edx ,@ax 
- MAP LINEAR ADDRESS TO GDT SELECTOR 
mov ax ,gdtsel 
movzx ecx,WORD PTR es:[bx].v86_len 
mov ebx ,edx 

. 286 
mov dl, DevH1p_LinToGDTSelector 
call  DWORD PTR [device_help] 
je error 
xor di, di 
jmp SHORT verify 


LJ 
, 
. 
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es = our data segment 
es:di -> gdt variable 
allocate 1 selector 


; alloc gdt sel function 


call device help 


; error, exit 


; set flag on 


; es:bx -> req pkt 

; es:bx -> data packet 
; v86mode segment 

; paragraph align 

; eax = offset, add 

- edx -> data buffer 


; get gdt selector 
; length of data buf 
’ ebx = linear addr 


map linear to gdt 
call device help 
if error, exit 
clear offset 


Figure 5. Device driver real-to-virtual address conversion routine (continued on page 94) 
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in the segment register, an incorrect- 
address translation occurs and an 
access to that memory results in the 
wrong physical memory or causes a 
protection violation. 

The steps necessary to convert an 
embedded V86 address to a virtual 
address usable by the device driver 
are demonstrated in Figure 5. The 
first step is to determine if the appli- 
cation making the DevI0Ctl request is 
a V86 mode process. This step is 
accomplished by obtaining the point- 
er to the local information segment 
(local info seg) and checking the 
process-type field. If the application 
is a V86 mode process, the embed- 
ded pointer must be converted to a 
virtual address. 

The local info seg address is 
obtained by calling the DevHlp GetD0S- 
Var service. The GetD0SVar service usu- 
ally is requested only once, in the 
device-driver initialization routine, 
and its address is saved in the device 
driver’s data segment and retrieved 
when needed. 


CONVERTING AN EMBEDDED 
DeviOCtil ADDRESS 

Once it has been determined that the 
address requires conversion, the 
device driver needs to: 


¢ Allocate a GDT selector 

* Convert the V86 address to its lin- 
ear address 

¢ Map the linear address to the 
GDT selector 

¢ Verify access to the buffer 
addressed by the GDT selector 

° Access the buffer 

¢ Free the GDT selector. 


To convert the V86 mode address 
to a virtual address, the device dri- 
ver must allocate a GDT selector by 
calling the DevHlp AllocGDTSelector ser- 
vice. The GDT selector is returned to 
the device driver in its storage 
addressed by the ES and DI registers. 
A GDT selector is a virtual address 
allocated in the global descriptor 
table and is available to the device 


driver at task and interrupt time. The 
global descriptor table is used by the 


processor to perform virtual-to-phys- 


ical-address translations. 
Next the device driver converts 
the V86 mode segment and offset 





address into a linear address by 
shifting the segment value left by 
four bits to obtain a paragraph 
address and adding the offset value. 
A paragraph address is a real 
address on a 16-byte boundary. 
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calculated, the device driver maps \ 

tor by calling the DevHlp LinToGDTSelec- ; OR SELECTOR AND OFFSET ADDRESS PASSED VIA GENERIC IOCTL REQUEST 
tor service. On completion of the Lin- 

ToGDTSelector call, the previously allo- — verdfy: 


Mi ) Once the linear address 9 b¢ Qh LLL Ts 


cated GDT selector is mapped to the les bx, reqpkt ; es:bx -> req pkt 
physical memory pointed to by the les bx, es: [bx] .GI0DataPack ; es:bx -> data packet 
embedded V86 mode segment and mov di,WORD PTR es:[bx].v86_off ; get v86 mode offset 
offset address. Notice that the Lin- mov ax, WORD PTR es: [bx]. v86_seg ; get v86 mode segment 
ToGDTSelector service requires parame- varied 4 ex,e8: (bx) .v86_2en {Bot Length: Oh ata fat 
ters to be passed in 32-bit registers, pk ae | | 
even though the OS/2 device-driver = dh, RACCESS ; : need read access 
model is a 16-bit model. The kernel ph A Tos on hha j Vera wovess Func 
memory-management routine that roe ae Eee ae oe help 

je error : if error, exit 


; CAN NOW DO WORK ON DATA AT ADDRESS IN AX:DI 


[he GetDOSVar service Is dovork: 
usually requested only aad ei 
once, and its address Is Pace Pre ON EL 


‘ ‘ les _— bx, reqpkt ; es:bx -> req pkt 
saved I the device mov es: [bx]. RPStatus,ERROR_INVALID_PARAMETER ; set return code 
; ; test flags, GDTALLOCATED ; if gdt not allocated 
Ve jz exitl ; then just exit 
drivers data segment and ee aes pote 
retrieved when needed. (CR ae ee oe 
exit: 
les — bx, reqpkt ; es:bx -> req pkt 
performs the LinToGDTSelector service mov es: [bx] .RPStatus , REQDONE * set return code 
is written using 32-bit instructions 
and requires 32-bit parameters. cleanup: 

With the GDT selector, the device les bx, localinfoseg ; get local info seg 
driver must verify that it may access cmp es: (bx].LIS_ProcType,LIS_PT_REALMODE =; if process != v86mode 
the memory before actually access- jne exit ; exit 
ing it. If, for example, the memory | 
permission is set to read-only, and ; FREE GDT SELECTOR 
the device driver tries to write into , 
it without first checking its access mov ax, gdt sel ; get gdt selector 
rights to the memory, a protection mov d1.,Deviilp_FreeG)TSelector ; free gdt sel Func 
violation occurs. Since the device call —DWORD PTR [device_help] ; call device help 
driver runs at ring 0 (the most pro- mov —_gdtsell, 0 ; clear gdt selector 
tected code), a protection violation at 
this level results in a system halt. To exitl: 
prevent a protection violation, the pet 
device driver must verify access to SORES (pOG 
the memory by calling the DevHlp (SEG EMDS 
VerifyAccess service before access- END 


ing It. 
An OS/2 application issuing a 
DevI0Ctl API executes in protected 
Figure 5. Device driver real-to-virtual address conversion routine (continued from page 92) 
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mode; its embedded selector and off- 
set address is already a virtual 
address and does not need address 
conversion. However, the device dri- 
ver is required to verify access on the 
protect-mode address before access- 
ing the memory. Once the code 
determines that the process is not a 
V86 mode process, instruction execu- 
tion continues at the DevHlp VerifyAc- 
cess call. 

The device driver uses either the 
GDT selector (with a zero offset) or 
the protect-mode selector and offset 
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to access the buffer containing the 
string PARMS_GO_HERE. When the 
device driver has completed its use 
of the buffer and, therefore, the GDT 
selector mapped to the buffer, it must 
free up the GDT slector by issuing a 
DevHlp FreeGDTSelector call. Of course, 
the FreeGDTSelector service only needs 
to be issued if the process is a V86 
mode process and a GDT selector 
was previously allocated. 

Some device-driver developers 
allocate GDT selectors when the 
device driver is called to initialize 
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and free GDT selectors when the 
device driver is called to deinstall. 
The benefit of this approach is the 
need to call the allocate and free 
GDT DevHlp services only once 
instead of each time a DevI0Ct1 call is 
made. 

If an error occurred during the 
processing of a DevHlp service, the 
device driver returns an appropriate 
return code in the status field of the 
kernel request packet. This return 
code is returned to the DOS or OS/2 
application in the AX register. 


Frank J. Schroeder, /BM/ Personal Soft- 
ware Products Division, 1000 N.W. 51st St, 
Boca Raton, Fla. 33431. Schroeder is a staff 
programmer in the OS/2 device drivers and 
multiple virtual DOS machines department. 
He has published articles in OS/2 2.x Note- 
book, OS/2 Developer, and IBM Personal 
Systems Technical Solutions. He earned a 
bachelor's of technology degree in computer 
science from Rochester Institute of Technol- 
ogy, New York, and an M.B.A. from the Uni- 
versity of Miami, Fla. 
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More REXX, GUL, SOM, 
And Other Tools 


TOOLS 
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PeerLogic PIPES Platform for IBM 0S/2 


Veo 

ile 2.1. PeerLogic’s PIPES Platform is a 
peer-to-peer distributed computing product for 
developing client/server applications. Platform 
independent, PIPES Platform is based on a sym- 
metrical, message-passing architecture that allows 
users to integrate PC LANs and SNA networks; 
TCP/IP and NetWare; OS/2, Windows, MVS, and 
UNIX at a single site or multiple remote lcoations. 


PeerLogic Inc. 

Phone: (415) 626-4545 Fax: (415) 626-4710 
Quadron qCF, qX25, gLAPB, and gCOM. gCF, gX25, 
and gLAPB are OS/2 2.x toolkits for the develop- 
ment of communication software for IBM’s ARTIC 
coprocessor cards. qCOM is a related turnkey 
product that provides multiple standard asyn- 
chronous OS/2 COM ports while offloading inter- 
rupt processing to an ARTIC card. Quadron’s line 
of communication software development tools are 
used in telephone network control, financial trans- 
action, airline reservation, process control, point- 
of-sale, and other communication applications. 


Quadron Service Corp. 
Phone: (805) 966-6424 Fax: (805) 966-7630 

Popkin SA Project Documentation Facility. The SA 
PDF provides users with desktop capabilities for 
creating complete analysis and design documents. 
It facilitates the creation and management of 
requirement, design, and system-level documenta- 
tion consistent with the System Architect CASE 
tool. 


Popkin Software & Systems Inc. 
Phone: (212) 571-3434 Fax: (212) 571-3436 
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WATCOM VX-REXX. VX-REXX is a visual solution 
builder for developing OS/2 2.x GUI applications. 
VX-REXX Operates with OS/2’s REXX, which 
means total availability of system APIs, and 
includes a project management facility, visual GUI 
form designer, and interactive source level debug- 
ger. 


WATCOM International Corp. 
Phone: (800) 265-4555 or (519) 886-3700 
Fax: (519) 747-4971 


ForeFront Software LAN Configuration Facility. LCF 
allows for automated installation of OS/2 and 
applications over a LAN. Software is stored in a 
central library on a a server where it can be 
accessed by users system-wide. LCF was devel- 
oped and used by the Royal Bank of Canada for 
mission critical applications. 


ForeFront Software Inc. 
Phone: (403) 531-2160 Fax: (403) 270-0372 

Gpf Systems Gpf (GUI Programming Facility). The new 
version of Gpf generates native OS/2 2.1 Presenta- 
tion Manager WorkPlace Shell and Windows 3.1 
interface code from a single design, facilitating a 
common look and feel across both platforms. The 
new version also supports C and C++ compilers 
and automatically generates dynamic linked 
libraries (DLLs). 


Gpf Systems Inc. 

Phone: (800) 831-0017 or (203) 873-3300 

Fax: (203) 873-3302 

Novell NetWare for 0S/2. NetWare for OS/2 is a net- 


working solution that lets companies combine the 
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advanced services of NetWare 4.01 and 
OS/2 while realizing significant cost 
savings through hardware consolida- 
tion. With NetWare, a single PC can 
function as a NetWare 4.01 server, an 
OS/2 application server, a gateway to a 
host computer, and a user workstation. 


Novell Inc. 
Phone: (801) 429-7000 
Fax: (801) 453-1267 


BocaSoft System Sounds and WipeOut. 
System Sounds associates pre-record- 
ed audio with a variety of system, 
mouse, or keyboard events, and 
includes a library of pre-recorded 
sound effects as well as an integrated 
record mechanism. WipeOut is an 


that 


audio/visual screen saver 
includes 16 animated displays with 
integrated digital audio. 


BocaSoft Inc. 

Phone: (407) 392-7743. 

Orders: Indelible Blue Inc. 

(800) 776-8284 or (919) 834-7005, 
Fax: (919) 783-8380 


Buzzwords WinGEN for 0S/2 2.1. WinGen 
for OS/2 creates 32-bit GUI DBMS 
database applications. The screen 
designer generates source code for sev- 
eral OS/2 C++ compilers. 


Buzzwords International Inc. 
Phone: (314) 334-6317 
Fax: (314) 334-0794 





Sector Seven DEPGEN 2.0. DEPGEN 
reads C source code and includes files 
to create a makefile and dependency 
list. Powerful new features support 
multiple directory projects, cross-com- 
pilers and linkers, libraries, and DLLs. 


Sector Seven 
Phone: (703) 866-9477 


Commix MultiMaster and DisplayMaster. 
MultiMaster is a tool for creating mul- 
timedia database applications. Dis- 
playMaster is a multimedia brows- 
er/organizer. 


Commikx SP Inc. 
Phone: (703) 356-9858 
Fax: (703) 356-6148 





UTILITIES 





CCT Back in a Flash! Back in 
3 a Flash! is an archive and 
backup facility for OS/2 2.1. In addi- 
tion to file compression and automatic 
backups, Flash! backs up files to 
diskettes, hard drives, and LAN- 
attached drives. 
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CCT Inc. 
Phone: (612) 339-5870 
Fax: (612) 339-5965 


Symantec Norton Commander O0S/2. Peter 
Norton’s latest brainchild is an OS/2 
2.x file management utility which fea- 
tures graphical manipulation of FAT 
and HPFS files. 


Symantec Inc. 
Phone: (800) 343-4714 
Fax: (303) 727-4611 


Software Builders ZIPMAN for 0S/2. ZP- 
MAN is a full-featured GUI interface 
for PKZIP and PKUNZIP file compres- 
sion/decompression utilities. It utilizes 
the Windows multi-document inter- 
face feature so that users can open 
more than one ZIP file at a time for 
viewing. 


Software Builders Inc. 
Phone: (800) 432-0025 or (404) 319-9621 


Rightware LinkRight. Rightware’s 
LinkRight is a 32-bit parallel and serial 
port file transfer utility. LinkRight fea- 
tures file copying to and from OS/2 
and DOS systems, file compression, 
CRC checking, and HPFS and long file 
name support. 


Rightware Inc. 
Phone: (301) 762-1151 
Fax: (301) 762-1185 





| APPLICATIONS 


| CadWare Pj2 CAD System. P\2 
J CAD System is a 32-bit 2D- 
3D CAD package for OS/2 2.x. Geo- 
metrical functions, graphic editing, and 
associative dimensioning round out 
CadWare’s latest release, Pj2 CAD Sys- 
tem uses multi-threading and fast sem- 
aphores and is highly customizable. 


CadWare, distr. by Indelible Blue Inc. 
Phone: (919) 834-7005 
Fax: (919) 783-8380 


Arcadia Workplace Companion for 08/2. 
Workplace Companion is a personal 
information manager designed for the 
OS/2 2.1 32-bit Workplace Shell envi- 
ronment. Calendar, clock, appoint- 
ments, telephone numbers, addresses, 
to-do lists, and notepad are all included. 


Arcadia Technologies Inc. 
Phone: (818) 446-6945 
Fax: (818) 447-4212 
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DEVELOPER SUPPORT 


IBM Developer Connection for 
0S/2. The IBM Developer 
Connection for OS/2 is a new service 
designed to provide OS/2 developers 
with the technical information needed 
to create OS/2 applications. The Devel- 
oper Connection will also feature 
updated information, tips, techniques, 
sample applications, and beta code for 
upcoming IBM applications. 
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The service, which consists of quar- 
terly CDs and newsletters as well as 
electronically-accessible developer sup- 
port, costs $199.95 per year. However, 
developers who sign up for the Devel- 
oper Connection before September 30, 
1993 are eligible for an introductory 
price of $149.95 per year. 


For more information about receiv- 


ing the Developer Connection, call 1- 
800-633-8266. 
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New I.V. League Catalogue. The IBM 
OS/2 Independent Vendor (I.V.) 
League showcases hundreds of 
books, magazines, courseware, and 
consulting services that support 
OS/2. Now, select member products 
are featured in the all new [.V. League 
Product Catalog. To order a free copy, 
call 1-800-342-6672. 









Every computer system has resources that must be shared by all applications executing in its environment. This 
article describes a performance monitoring tool that can help determine whether those resources are being 
used effectively. BY LAURA ADAMS 


SPM /2: Fine-Tuning 
Your Application 
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Laura Adams 





n any single computer system or net- 

work of systems, there are limited 

resources (such as CPU, RAM, and 
disk) that need to be shared by all applica- 
tions executing in that environment. Comput- 
er system users, system administrators, and 
application designers are all interested in how 
to obtain the most efficient use of these 
resources and the highest performance at the 
lowest cost. This means figuring out how to 
modify parameters, applications, and work- 
loads so the limited resources are used most 
effectively. To accomplish these tasks, perfor- 
mance data collection and monitoring tools 
are needed, as well as information on how to 
interpret the data and where to apply the 
interpretation in tuning the system. 


2.1, small fixes are needed for Theseus2 and 
the SPM/2 Query function. These fixes can be 
obtained from OS2TOOLS (SPMFIXES pack- 
age), OS2BBS (SPMFIXES package under 
“OS/2 Selective Fixes” in the Software 
Library), or CompuServe (SPMFIX.ZIP file of 
Library 9 in the OS2DF2 forum). 


SPM/2 2.0 OVERVIEW 

SPM/2 2.0 consists of performance data collect- 
ing, recording, graphing, reporting, and analyz- 
ing facilities that enable performance manage- 
ment of critical OS/2 2.x system resources, as 
well as resources of 16- and 32-bit applications 
executing in an environment of OS/2 2.0 plus 
Service Pak XR06055 or higher. In addition to 
collecting performance data locally on a given 


Computer system users, system administrators, and application 
designers are all interested in how to obtain the most efficient 
use of resources and the highest performance at the lowest cost. 


This article discusses System Performance 
Monitor/2 2.0 (SPM/2 2.0), a performance 
monitoring product for the 32-bit OS/2 envi- 
ronment that helps accomplish performance- 
related tasks. To run SPM/2 2.0 under OS/2 


system, SPM/2 2.0 supports remote monitoring 
of IBM OS/2 LAN Servers and Requesters via a 
remote named pipe interface. Monitoring is pos- 
sible from OS/2 LAN Server running OS/2 2.x 
or OS/2 LAN Requester 3.0 with Peer Services. 
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Figure 1. SPM/2 Graphing, Control Panel, and Theseus2 


SPM/2 2.0 provides the following key features: 


A Presentation Manager-based control 
panel providing centralized control for per- 
formance monitoring activities 

Collection of extensive performance metrics 
for CPU, memory, files, disk, cache, printer 
port, and communication port resource per- 
formance data 

Collection of user-defined performance met- 
rics from user-written applications 
Discovery capability of LAN-attatched 
SPM /2-enabled workstations 

Support for multiple concurrent monitoring 
sessions 

Concurrent graphing and _ recording 
activity 

Graphical playback of previously recorded 
data 
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¢ Ability to graphically view performance of 


any workstation within a single monitor 
session 

Workstation-, application-, process- and 
thread-level report filters 


| Support for processing multiple recorded 


log files into a single report 

Enhanced function and usability for the 
memory analyzer, including a Presentation 
Manager- and Hyperblock-based interface 
API Support enabling user applications and 
device drivers to register performance met- 
rics for collection 

API Support enabling collection of real-time 
performance data and processing of histori- 
cal data 

Online hypertext user guide and references 


SPM/2 2.0 is primarily useful in an appli- 
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cation development or small LAN 
environment, For application devel- 
opers, SPM/2's performance infor- 
mation and user-hook capabilities 
can help produce more efficient 
applications, help locate defects, 
and choose smarter application 
designs. In a small LAN environ- 
ment, performance data collected 
by SPM/2 2.0 can help isolate prob- 
lems quickly and accurately, speed- 
ing resolution. 

For system administrators re- 
sponsible for watching the perfor- 
mance of a large number of remote 
LAN-attatched systems, SPM/2 2.0 
can be combined with LAN Man- 
agement Utilities/2 2.0 (LMU/2 
2.0). LMU/2 adds the capability to 
define thresholds on the various 
resources collected by SPM/2 and 
generates alerts when a threshold is 





When multiple work- 
stations are monitored 
froma single .LOG file 

_ the performance data for 
— thems recorded into the 
~ same .LOG Tile. 






exceeded. These alerts can also be 
routed to NetView on the host. 
LMU/2 also stores performance 
data collected from SPM//2 2.0 in an 
OS/2 database, allowing an admin- 
istrator to run reports and look at 
performance and capacity trends 
over time. 


SPM/2 2.0 PRODUCT FUNCTION 
The following sections describe 
functions provided by SPM/2 2.0. 
Figure 1 illustrates several of these 
functions. 
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SPM/2 2.0 Control Panel. The central 
point of control for an SPM/2 2.0 
function is a Presentation Manager- 
based control panel from which 
users can define the characteristics 
of each monitoring session (work- 
stations, resources, collection fre- 
quency, and so on), control the 
starting and stopping of graphing 
and recording activities, and run 
reports from recorded data. 

While monitoring is active, the 
control panel lists the monitoring 
sessions, their status, and the set of 
workstations being monitored for 
each session. 


Defining Monitoring Sessions. Moni- 
toring sessions are controlled by 
monitor session description, or 
-LOG, files. These files contain the 
description of the monitor session, 
as well as any data recorded during 
monitoring. The monitor session 
description includes: 


Workstations—The user’s first 
specifications when creating a .LOG 
file are the names of the worksta- 
tions to be monitored. To aid in 
identifying the names of worksta- 
tions on the LAN, SPM/2 provides 
a query function that asks the net- 
work for the names of workstations 
enabled for SPM/2 2.0 performance 
data collection. This gives users a 
list from which to choose. When 
multiple workstations are moni- 
tored from a single .LOG file, the 
performance data for these work- 
stations is recorded into the same 
.LOG file. 


Resources—SPM/2 collects per- 
formance data from architected per- 
formance metrics, or “hooks,” in the 
OS/2 2.0 operating system. These 
hooks are simply counter and timer 
control blocks that count the occur- 
rences of various events and activi- 
ties in the system. They do not gen- 
erate messages or event records— 


SPM/2 only gets performance data 
when it specifically asks for it. 


Users can select several major 
resources when defining a monitor- 
ing session (with examples of the 
details collected by SPM/2 in 
parentheses). These include: 


¢ CPU (execution and interrupt 
time) 

¢ Physical disk (number of read 
and write operations, bytes read 
and written, time spent reading 
and writing) 

¢ Memory (paging information: 
faults, page ins and outs, num- 
ber of pages discarded, present, 
and free) 

e Files (time spent reading and 
writing files, number of bytes 
read and written) 

*« FAT cache (cache hits and misses 
for reads and writes, cache 
bypasses) 

* HPFS cache (cache buffer infor- 
mation, number of file open and 
closed) 

¢ Printer port (number of printer 
write operations and number of 
bytes written) 

¢ Communications port (number 
of communications port reads 
and writes, bytes read and writ- 
ten, time reading and writing, 
number of software and hard- 
ware overrun errors). 


In addition to specifying which 
resources are to be collected, users 
also specify whether or not to col- 
lect application-, process-, and 
thread-level data. 


Collection and Recording Frequen- 
cies—The collection frequency defines 
how often SPM/2 reads performance 
data from the operating system. The 
recording frequency, which must be a 
multiple of the collection frequency, 
defines how often the recording appli- 
cation averages samples read at the 
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Figure 2, SPM/2 2.0 process-level report 
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Figure 3. Example of system working set 


collection frequency and stores them 
in the .LOG file. 

Although SPM/2 has optimized 
its overhead, two things affect intru- 
siveness during data collection. First, 
specifying collection of application-, 
process-, or thread-level data will 
result in more counter control blocks 
(one for every process and thread in 
the system) and hence more data will 
be read. Also, the collection frequen- 
cy will determine how often data is 


read. Specifying a smaller collection 
frequency will, of course, result in 
more data being read. 

In both situations, reading more 
data results in larger .LOG files 
when recording and, in a remote 
environment, more LAN traffic. 
You can work with these two para- 
meters to achieve a balance accept- 
able for your monitoring situation. 


Graphing and Recording. Monitoring is 


started by selecting the desired 
.LOG file and then choosing Graph- 
ing, Recording, or Both. SPM/2 2.0 
allows you to graph and record at 
the same time. The status window of 
the SPM/2 control panel will 
remind you which functions are 
active for a particular .LOG file. 

The graphing facility provides a 
graphical presentation of utilization 
on a system-wide basis for the fol- 
lowing resources: 


OS/2 DEVELOPER 





e CPU 

e Physical disk (up to 24 physical 
drives, with support for SCSI, 
ESDI, and ST-506 device drivers) 

¢ Memory utilization, | which 
includes the total physical memo- 
ry (the value displayed in the title 
bar), used memory, working set 
memory (the number of pages 
touched during a specified peri- 
od of time), resident (nondiscard- 
able and nonswappable) memory, 
pages swapped in, and pages 
swapped out. 


To obtain detailed process- and 
thread-level information or data 
about other system resources, the 
recording and report functions 
must be used. 

Although your .LOG file may be 
defined to monitor multiple work- 
stations, the graphing facility dis- 
plays the activity for only one 
workstation at a time. However, by 
clicking on the Node icon in the 
graphing window, you will be pre- 
sented with a list of the worksta- 
tions defined in the active .LOG file 
and you can change which worksta- 
tion is being graphed. A status bar 
in the graph window tells you the 
.LOG file name and specific node 
currently being graphed. 

Usability features of the graph- 
ing facility include: 


¢ A legend that defines what each 
line in the graph represents 

¢ The current time displayed across 
the X-axis of each graph window 

¢ A cross-hair cursor that can be 
positioned over any point on a 
graph line and clicked to display 
the exact X/Y value (time and 
percent utilization) of that point 

¢ Ability to select graph colors. 


The graphing facility also has a 
playback function that allows you 
to review previously recorded data. 
If your monitor session was started 
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with simultaneous graphing and 
recording, you can switch over to 
playback mode at anytime and 
review the data already recorded 
during that session. Current perfor- 
mance data will continue to be 
recorded to the .LOG file while in 
playback mode. 


Running a Report. Before running a 
report, users create a_ report 
description (.RDF) file that defines 
the .LOG file(s), resources, summa- 
rization level (workstation, process, 
or thread), and format to be used in 
creating that report. An administra- 
tor could have a standard set of 
monitoring session descriptions to 
be run on a regular basis, with cor- 
responding .RDF files for generat- 
ing periodic summary reports. 
Multiple .LOG files can be com- 
bined into one report, although it is 


from the operating system and pro- 
duces more meaningful utilization 
information. Examples of informa- 
tion calculated by the report facility 
are: 


¢ Percentage of CPU utilized by 
process and thread 

e Average physical disk read and 

write times 

Page-in and page-out rates 

Paging disk utilization 

Cache hit and miss ratios 

Average file read and write 

times 

¢ Printer and communication port 
throughput rates 


To locate a performance problem 
using the report facility, you can 
specify a subset of resources to ana- 
lyze, a subset of the time period to 
analyze, and the report summariza- 





lo locate a performance problem with the report 
facility, you can specify a subset of resources to 
analyze, a subset of the time period to analyze, 
and the report summarization level, which defines 
how detailed the report's. 


advised that the same resources be 
collected in each .LOG file. Com- 
bining .LOG files might be useful if 
new workstations are added to the 
network at a time when it is incon- 
venient to add these workstations 
to the existing .LOG file (mid-week, 
for example). By defining a new 
.LOG file for the new workstations, 
data could be collected from those 
workstations and then folded into 
the weekly report. 

In generating a report, the 
SPM /2 report facility performs cal- 
culations on the raw data collected 
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tion level, which defines how 
detailed the report is. The summa- 
rization levels supported (from 
least to most detail) are worksta- 
tion, application, process , and 
thread. 

Specifying any of the more 
detailed levels will include all the 
lesser-detailed levels of detail in the 
report. For example, a process 
report will include summary lines 
for each application and worksta- 
tion. Figure 2 shows an example of 
a process-level report. 

If an application summarization 
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level is specified, SPM/2 will group 
processes from the same applica- 


| tion under a common application 


name and include a resource sum- 
mary line for that application. Sev- 
eral OS/2 system applications (such 
as LAN Server and Communica- 
tions Manager) come predefined 
with SPM/2. Additionally, SPM/2 
provides the capability of defining 


_ SPM/2 APIs enable 
application and device- 
driver developers to 
define and register 
application-specitic 
counters and timers that 
can help optimize code 
performance. 
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your own applications as any set of 
executable modules. 

The supported report formats are 
summary, tabular, delimited (spread- 
sheet compatible), and dump (raw 
performance data values). 


Memory Analyzer: Theseus2. The 
SPM/2 Memory Analyzer (The- 
seus2) provides application devel- 
opers with insight into OS/2 mem- 
ory management. An important fea- 
ture of Theseus2 is its capability to 
provide working set information 
(which gives the amount of memo- 
ry actually referenced over a given 
time interval). Working set infor- 
mation can help you more accurate- 
ly determine the amount of physi- 
cal memory needed in your system 
to minimize swapping. Figure 3 
shows an example of a system 


working set report for an interval of 
about 1.5 minutes. 

Some important usability fea- 
tures of Theseus2: 


¢ A main window that displays all 
processes currently active in the 
system. This is useful for know- 
ing whether or not background 
processes are still active. 

* A Presentation Manager inter- 
face into OS/2 memory manage- 
ment information 

¢ Hyperblock linking that allows 
navigation from one memory 
control block to another by sim- 
ply double-clicking (with the 
mouse) on the address of the 
control block to be viewed 

* Ability to output reports to the 
printer or a file and highlighted 
text to the printer or the clip- 
board 

¢ Extensive help that explains 
every field of the Theseus2 win- 
dows 

e On-line hypertext documenta- 
tion that provides valuable infor- 
mation about OS/2 2.x memory 
management concepts. 


Examples of the memory infor- 
mation provided (which can be dis- 
played as linear, virtual, or physi- 
cal addresses) are: 


¢ System information—loaded device 
drivers and modules, a global 
descriptor table, system anchor seg- 
ment, system memory usage, sys- 
tem arena and page tables, free, 
idle, or locked memory, memory 
utilization, and working set for the 
entire system. 


e Process Information—per task 
data area, local descriptor table, 
page table, private and shared 
arena tables, memory utilization, 
and working set by individual 
process. 

¢ Register information—processor 


control registers, current inter- 
rupt descriptor table, and cur- 
rent task state segment. 


Directory Analyzer. The SPM /2 direc- 
tory analyzer provides the capabili- 
ty to analyze disk capacity (data file 
and size) information and report 
the information by directory, subdi- 
rectory, file, and cluster level. The 
specific information provided 
includes the data size of any file in 
bytes (how much data is in the file), 
the file allocation size (the number 
of clusters on a disk), and the count 
of files on the disk. 


Application Programming Support. 
SPM/2 supports APIs of two types. 
One type enables line-of-business 
applications to process performance 
data in real time, allowing an appli- 
cation to initiate and terminate 
monitoring sessions, open and close 
.LOG files, and read data from 
those files. These applications can 
then utilize the data in ways specif- 
ic to the particular business. 

Other SPM/2 APIs enable appli- 
cation and device driver developers 
to define and register application- 
specific counters and timers that 
can help optimize the performance 
of their code. Once registered with 
the operating system, SPM/2 will 
see these user-defined metrics and 
read them along with the OS/2 2.0 
resource metrics. The values of 
these user-defined metrics can be 
formatted and viewed using the 
Report Facility’s Dump format. 


Command Line Interface. Commands 
are provided to start and stop the 
data collection functions, graphing, 
recording, as well as run reports. 
This command-line interface en- 
ables SPM/2 facilities to be remote- 
ly executed from a NetView-based 
workstation using the IBM Remote 
Operations or IBM Distributed 
Console Access Facility programs. 
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USING THE SPM/2 2.0 DATA: 

AN APPROACH 

With these functions, users can nar- 
row in on a performance problem 
by first running the graphing facili- 
ty to see which resources (CPU, 
disk, or RAM) are being used. 
Users can also choose to start 
recording simultaneously with 
graphing, then generate a worksta- 
tion-level report to see information 
not displayed in the graph (such as 
paging information or number of 
bytes read and written to the disk). 

Depending on which resource 
appears to be a problem, either more 
data should be collected or Theseus2 
should be used. For any resource 
problem other than memory, modify 
the .LOG file description to specify 
collection of additional related 
resources (for example, if disk is a 
problem, ask for File information to 
see which files are being used heavi- 
ly). You will probably want to 
include application-, process-, and 
thread-level detail to generate more 
comprehensive reports. 

Rerun the scenario of interest 
with this modified .LOG file, then 
run a summary report for the entire 
scenario and see which processes or 
files are involved in the problem. 
Also try playing back the .LOG file, 
pausing at locations of peak activi- 
ty. With the cross-hair cursor, 
determine times that surround the 
period of peak activity. Using these 
times, run other reports, isolating 
just this time period. Then focus on 
the processes using the most 
resources, asking what these 
processes might be doing and how 
things might be changed. 

If the resource of concern is 
memory, including heavy swap- 
ping activity, the Theseus2 memo- 
ry analyzer should be used to deter- 
mine how much memory each 
process is using, as well as the level 
of swap activity. 
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SCENARIOS 


Scenario 1. A particular company has 
a Database Manager application 
running at several remote sites, each 
with its own database server. The 
headquarters location has been get- 
ting complaints that things are slow- 
ing down during certain periods 
each day. This information is insuffi- 
cient to determine the problem. 

To narrow in on the problem, 
remote SPM/2 2.0 monitoring ses- 
sions are initiated to run over the 
time during which complaints are 
received. An initial look at the 
reports indicates that server activity 
changes from relatively quiet to 
quite congested in a short period of 
time (as determined by the number 
of new processes that appear in the 
report). Further monitoring and use 
of Theseus2 reveals that swapping 
activity also increases during this 
time. 

To obtain more information, 
employees are asked what they typ- 
ically do during these periods. It is 
discovered that after initially 
accessing the database in the morn- 
ing, people drift into other work. 
Later, after a midmorning break, 
they return to their workplaces and 
start initiating transactions against 
the database, causing many appli- 
cations previously swapped out 
due to inactivity to be swapped 
back into the system and run con- 
currently. It is decided to add more 
RAM to the servers, as well as 
define some employee work proce- 
dures, to alleviate the situation. 


Scenario 2, A certain business appli- 
cation is found to be getting slower 
and slower. SPM/2 2.0 shows that 
the most heavily used resource is 
the physical disk. When SPM/2 is 
run again, this time requesting File 
information, reports show that sev- 
eral data and logging files owned 
by the application are continually 
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accessed. In addition, application 
code is loaded quite frequently and 


is found to reside on the same disk | 


as the data and logging files. 

More detailed analysis is per- 
formed (by changing collection fre- 
quency and report intervals) to 
determine exactly when the various 
files and program modules are 
accessed. As a result, a new physi- 
cal disk and disk controller is 
added to the system. Files and pro- 
grams are moved to this new disk 
so that when they are accessed dur- 
ing the same period they are not on 
the same disk. 





Depending on which 
resource appears to 
be a problem, either 
more data should be 
collected or [heseus2 
should be used. 


Scenario 3. During testing of an 
application under development, it 
is found that the system almost 
grinds to a halt when certain com- 
mon tasks are performed. In some 
cases, the keyboard stops respond- 
ing completely. SPM/2 is brought 
in, data is recorded to a .LOG file, 
and a process- and thread-level 
report is run. The CPU section gets 
immediate attention because a few 
application processes monopolize 
the CPU while others appear 
unable to get any processing time, 
even though it would be expected 
that they get at least a small 
amount of the CPU. 

Theseus2 is run to find the prior- 
ity of each active process. It is dis- 
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covered that several of the applica- 
tion processes have set their own 


priorities to time-critical, rather 


than relying on the OS/2 scheduler 
to share the CPU appropriately 
among the processes. Further ques- 
tioning also reveals that PRIORITY 
has been set to ABSOLUTE in 
config.sys. (Setting PRIORITY to 
ABSOLUTE keeps some of the OS/2 
components, such as Communica- 
tions Manager, from being able to 
dynamically modify the priorities 
of certain time-dependent pieces of 
code.) 

The developers are asked to let 
the operating system set the priori- 
ties of their processes. If needed, 
minor adjustments can be made 
later (but nothing so drastic as set- 
ting PRIORITY to time-critical). 


Scenario 4. The developer of an 
application wants to optimize the 
application’s performance as much 
as possible, One of the resources 
that needs optimizing is the inter- 
nal buffers, which are allocated and 
released as needed. The developer 
defines application-specific coun- 
ters and timers to see how often 
these buffers are allocated and to 
determine the maximum number 
needed during certain critical peri- 
ods of the application. 

These metrics are registered with 
the operating system with SPM/2 
APIs. The developer then has the 
application update the counters 
whenever the buffers are allocated 


and released. With this information, 
the developer can determine the opti- 
mal size of each buffer so buffers 
aren't allocated too often (which 
causes excess processing overhead), 
and the buffer space isn’t too large 
(which results in excess unused 
memory being tied up). 


CONCLUSION 
Performance measurement and 
analysis is required at every stage 
in the lifecycle of a LAN system, 
including planning, design, imple- 
mentation, use, and maintenance. 
This type of analysis can show how 
well a LAN system is performing 
and whether tuning is required. 
SPM/2 and LMU/2 provide 
capabilities for collecting, monitor- 
ing, logging, reporting, and analyz- 
ing system performance data. 
Future products will expand on this 
base of information, enabling more 
control from a centralized location. 


Laura Adams, /BM Corp., 11400 Burnet Ra., 
Austin, Texas 78758, Adams is an advisory 
programmer in the LAN systems area of 
IBM's Personal Systems Products division. 
She joined IBM in 1976 and in 1986 joined 
the OS/2 Database Manager development 
team. She is currently working in market sup- 
port and planning for SPM/2 and LAN 
NetView Monitor. Adams holds a B.A. in 
mathematics fram Hope College. 
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Performance enhancements, simple to complex, consume a great deal of time. The link step, however, is often 
overlooked in the quest for a smaller, faster application. This article describes LINK386 options that relate to 


performance. BY ALLEN WYNN 





Using LINK386 Options 
To Improve Performance 






erformance enhancements, simple to com- 
_ plex, consume a great deal of time. The 

link step, however, is often overlooked in 
the quest for a smaller, faster application. This arti- 
cle describes LINK386 options that relate to per- 
formance. LINK 386, a utility that ships with OS/2 
2.x and the OS/2 Toolkit, can help improve speed 
and reduce size in your applications. 


/ALIGNMENT 

The /ALIGNMENT option specifies the alignment factor 
for an executable. The alignment factor is used to 
determine the starting offset of all pages within 
the executable file. The parameter must be a power 
of 2 and must be in the range of 2 to 32,768. All 
pages in the executable will be based on a multiple 
of n bytes from the beginning of the file. 

Alignment factors greater than 4,096 will waste 
disk space because pages in OS/2 are 4,096 bytes 
in length. An alignment factor of 2 will produce 
the smallest executable. 

The default alignment factor of 512 will pro- 
duce an executable with pages that are sector 
aligned. This may produce an executable that 
loads marginally faster. The file will usually be 
much larger, and the marginal load performance 
does not usually offset the additional disk space 
requirements. 


/BASE 

The /BASE option specifies a preferred load address. 
The preferred base address is rounded up to the 
nearest multiple of 64K. The first object is assigned 
the preferred load address. Each additional object 
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is assigned the next available multiple of 64K. 
LINK386 will then pre-apply all internal relocation 
records based on the preferred load address. 

All .EXE files are loaded at a base address of 
64K, so the preferred load address for a .EXE must 
be 64K. If another preferred load address is speci- 
fied for an .EXE, a warning message will be dis- 
played, and the preferred load address will be 
assigned to 64K. Because the .EXE file is guaran- 
teed to be loaded at its preferred load address, 
LINK386 will not write the internal relocation 
records to the target file. This results in a smaller 
file because there are no internal relocation 
records. The executable will load faster because 
the internal fixes do not have to be applied while 
the program is loading. 

A dynamic link library (DLL) can be based as 
well; however it is not recommended. The actual 


If another module has been loaded 
ina DLLS preferred load adaress, 
the loader will need to reapply the 
internal relocation records. 


load address cannot be determined until run time. 
If another module has been loaded in a DLL’s pre- 
ferred load address, the loader will need to reap- 
ply the internal relocation records. LINK386 must 
write the internal relocation records of the DLL to 
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the target file, so they will be available 





to the loader. Basing a DLL will not 
result in a smaller file. If the loader has 
to reapply the internal relocation 
records of a DLL, the DLL will actually 
load more slowly than if the DLL was 
not based. 

The preferred load address for an 
.EXE must be 0x10,000 (64K). The pre- 
ferred load address for a DLL should 


be a large number less than 
0x18000000. 
/DEBUG or /CODEVIEW 


The /DEBUG option directs LINK386 to 
look for symbolic data and line num- 
ber information in object modules and 
include this information in the exe- 
cutable file. The /CODEVIEW option pro- 
duces exactly the same results as the 
/DEBUG option, regardless of the symbol- 
ic debug format (for example, AIX 
style, IBM PM Debugger, and so on). 
While the /DEBUG option is a popular 
debugging tool, symbolic debugging 
information should only rarely be 





Figure 1. /FARCALLTRANSLATION replacement code for CALL FAR 








Figure 2. /FARCALLTRANSLATION replacement code for JMP FAR 


to compress pages within the exe- 
cutable. These pages are automatically 
expanded when the program is execut- 
ed. 
The current /EXEPACK algorithm com- 
presses patterns of repeated bytes in 
pages of data. Pages of code do not 
usually have patterns of repeating 
bytes long enough to make packing 
worthwhile. 

The /EXEPACK option will not always 
create a smaller executable. However, 


To achieve maximum compression with the 
/EXEPACK flag, all data items that have the 
same initial value should be in the same area 
of the data segments. Any data items that are 
not initialized to a nonzero value can be 
initialized to zero. 
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included in executables that are 
shipped as part of a final product. 


/EXEPACK 
The /EXEPACK option is probably the 
most ignored LINK386 option, howev- 
er, it can produce significantly smaller 
executables. These smaller executables 
usually load faster and perform better 
under low-memory, high-swapping sit- 
uations. 

The /EXEPACK option causes LINK386 


an executable linked with LINK386 and 
the /EXEPACK option will not be larger 
than the same executable linked with 
LINK386 without the /EXEPACK option. 

To achieve maximum compression 
with the /EXEPACK flag, all data items that 
have the same initial value should be 
in the same area of the data segments. 
Any data items that are not initialized 
to a nonzero value can be initialized to 
zero. 

In addition to saving disk space, the 


/EXEPACK flag will usually cause your 
program to load faster. The amount of 
time to read a section of compressed 
data from disk and decompress the 
data in memory is usually less than the 
time to read an uncompressed page 
from disk. 


/FARCALLTRANSLATION 

The /FARCALLTRANSLATION option causes 
LINK386 to optimize far calls and far 
jumps to the same segment. The CALL 
FAR instruction is replaced with the code 
shown in Figure 1, and the JMP FAR 
instruction is replaced with the code 
shown in Figure 2, 

These new instruction sequences 
eliminate loading a segment register on 
the call or jump, which results in faster 
execution when running in protect 
mode. A load-time relocation is elimi- 
nated, resulting in a smaller file that 
loads faster. 

The /PACKCODE option is often used in 
conjunction with the /FARCALLTRANSLATION 
option. The /PACKCODE option can be used 
to combine code segments, potentially 
increasing the number of CALL FAR and 
JMP FAR instructions made to a target 
address in the same segment. The /FAR- 
CALLTRANSLATION option does not affect 
near calls. 


/PACKCODE 

The /PACKCODE option does not compress 
code. The /PACKCODE option combines 
adjacent code segments. Adjacent code 
segments receive the same segment 
address, and offsets are adjusted as 
required. 
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If a number is specified, it defines 
the maximum size of a code segment 
grouped by the /PACKCODE option. If no 
number is specified, the maximum size 
will be 65,530. LINK386 will stop 
adding segments to a group when the 
next segment will cause the size to 
exceed the specified size. 

LINK386 will pack code segments 
by default; this option is provided to 
override a /NOPACKCODE option specified 
in the LINK386 environment variable. 


/PACKDATA 

The /PACKDATA option does not compress 
data. The /PACKDATA option combines 
adjacent data segments. Adjacent data 
segments receive the same segment 
address, and offsets are adjusted as 
required. 

If a number is specified, it defines 
the maximum size of a data segment 
grouped by the /PACKDATA option. If no 
number is specified, the maximum size 
will be 65,530. LINK386 will stop 
adding segments to a group when the 
next segment will cause the size to 
exceed the specified size. 


/RUNFROMVDM 

LINK386 inserts a DOS stub or code 
segment, which is loaded and run 
when an application is executed in 
DOS, the DOS Box of OS/2 1.x, or ina 
Virtual DOS Machine in OS/2 2.x. 

The /RUNFROMVDM option is new for 
OS/2 2.1 and causes LINK386 to use an 
alternate DOS stub. This alternate DOS 
stub will print a message and exit if the 
program is executed in DOS, the DOS 
Box of OS/2 1.x, or a Virtual DOS 
Machine in OS/2 2.0. If the program is 
executed in a Virtual DOS Machine in 
OS/2 2.1, the system will cause the pro- 
gram to be started in protect mode. 

The /RUNFROMVDM option does not cre- 





Figure 3, LINK386 Environment Variable example 


ate a smaller executable or an executable 
that will load faster if started from pro- 
tect mode. However, if the user tries to 
execute the program from a Virtual DOS 
Machine in OS/2 2.1, the user will not 
be required to switch to a protect mode 
session and retype the command. 


/STACK 

The /STACK option specifies the stack 
size, in bytes, for the program. Any 
positive value can be specified. If a pro- 
gram uses little stack space, decreasing 
the stack size will conserve memory. 


LINK386 ENVIRONMENT 
VARIABLE 
The LINK386 environment variable 
specifies LINK386 options that are to be 
used each time LINK386 is invoked. 
The LINK386 environment variable is 
processed before the command line 
options. 

In Figure 3, the LINK386 environ- 
ment variable is set to include the 
/EXEPACK, /FARCALLTRANSLATION, and /ALIGN- 





MENT:2 LINK386 options. The /ALIGNMENT 
option has been abbreviated to /ALIGN 
and the /FARCALLTRANSLATION option has 
been abbreviated to /FARCALL. 

In this example, programl is linked 
using the /EXEPACK, /FARCALLTRANSLATION, 
and /ALIGNMENT:2 LINK386 options. Pro- 
gram2 is linked using the /EXEPACK, /FAR- 
CALLTRANSLATION, /ALIGNMENT:2, and /STACK- 
SIZE:0x2000 LINK386 options. Program3 is 
linked using the /EXEPACK, /FARCALLTRANS- 
LATION, /ALIGNMENT:4, and /RUNFROMVOM 
LINK386 options. 


Allen Wynn, /BM Corp., 1000 N.W. 51st 
St., Boca Raton, Fla, 33432. Wynn is a 
senior associate programmer in OS/2 
development. Since joining IBM in 1987, he 
has worked on OS/2 System Test, OS/2 
device drivers and MVDM, and OS/2 kernel 
and file systems. His current assignment Is 
in the OS/2 system performance depart- 
ment. He received a B.S. in information and 
computer science from the Georgia Insti- 
tute of Technolagy. 
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and dBAS. 


Fieve is a good reason why 

your database language was 
developed in C. In fact, there 
are many good reasons. 


C code is small. C code is fast. C code is 
portable. C code is flexible. C is the 
language of choice for today's professional 
developer. With the growing complexity of 
database applications, C is a realistic 
alternative. Now with CodeBase 5.0, you 
can have all the functionality, simplicity and 
power of traditional database languages 
together with the benefits of C/C++. 


C speed - fast code, true executables... 
FoxPro, Clipper, and dBASE were written 
in C primarily for speed. But those compilers 
don't really compile, they combine imbedded 
language interpreters into your .EXE. Now 
that's slow. For dazzling performance you 
need the true executables of C. With 
CodeBase you get the real thing, C code. 
Consider the following statistics, from the 
publisher of Clipper: 








"Sieve of Erastothenes" | 
Benchmark for Prime Number Generation 
Shows C to be incredibly faster ! 


C size - small executables, 

no added overhead... 

FoxPro, Clipper and dBASE would like you 
to believe you need their entire development 
system to build database applications. But 
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remember, those products are all written in 
C. So why do you need to lug all their extra 
code around? You don't. CodeBase is a 
complete DBMS, in C. No fat executables 
stuffed with unused code. No runtime 
modules. No royalties. Just quality C code. 
CodeBase is just what you need. 


C portability - ANSI C/C++ 

on every hardware platform... 

No other language exists on more platforms 
than C/C++. Why rewrite your entire 
application for DOS, Windows, Windows 
NT, OS/2 or UNLX? With CodeBase the 
complete C source code is included, so you 
can port to any platform with an ANSI C or 
C++ compiler. Now and in the future. 


dBASE Compatible data, index 
and memo files... 

You want the industry standard. You need 
compatibility. Sure, dBASE is the standard, 
but every dBASE compatible DBMS 
product uses its own unique index and memo 
file formats. Only CodeBase has them all: 
FoxPro (.cdx), Clipper (.ntx), dBASE IV 
(.mdx) and dBASE III (.ndx). Now it's your 
choice, we're compatible with you. 


Announcin 
CodeBase 5. 


The power of a complete DBMS, the benefits of C 


NEW - Multi-user sharing with 
FoxPro, Clipper and dBASE... 
Now your multi-user C/C++ programs can 
share data, index and memo files at the 
same time as concurrently running FoxPro, 
Clipper and dBASE programs. No 
incompatibilities. No waiting. 


NEW - Queries & Relations 
1000 times faster... 


CodeBase 5.0 now lets you query related 
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data files with any logical dBASE expression. 
Our new Bit Optimization Technology 
(similar to FoxPro's Rushmore technology) 
uses index files to return a query on a 1/2 
million recerd data file in just a second. 
Automatically take advantage of this query 
performance by using our new CodeReporter: 









16 944,737.00 

tM | 90.70.00 
To use CodeReporter, 
simply draw your report, then include it in any 
program you write. Call 403/437-2410 now for 
your FREE working model of CodeReporter. 


New - Design complex reports 

in just minutes... 

Our new CodeReporter takes the painstaking 
work out of reports. Now simply design and 
draw reports interactively under Windows 31, 
then print or display them from any DOS, 
Windows or UNIX application. 


SPECIAL - FREE CodeReporter 
Order CodeBase 5 before October 31, 1993 
and receive CodeReporter for free! This 
offer includes our no-risk, 90-day money 
back guarantee, so order today! 
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Why it’s smart to go with the standard 








@ Multimedia 

® Books, classes, and video 
‘filog 

= Communications 

@ User interface libraries for 





Look for this mark on third-party software 
products that enhance Borland tools. 


DOS, Windows, and OS/2 
The tools of choice for mit arash es 
| ) ane f processing 
Windows, BOS, and 03/2 ith <ciemifc, and 
Use Borland tools and you have engineering libraries 


more than the world’s best lan- | 
guages. Much more. Borland* 

Pascal and Borland® C++ for 
Windows, DOS, or OS/2® give you 
access to the largest resource of 
libraries, custom controls, and other 
add-ins. Whether your projects are | 


@ Source control 

@ Embedded systems tools 

@ Object-oriented design tools 
B® Utilities 

@ Testing automation 


in client/server architecture or in 
embedded systems, Borland has 
_ forged partnerships with third- 







B Borland is the market leader 


67% 







| party developers to help you get 
the job done fast. 


To set standards, 





| _ When you use Borland tools, it’s 
Worldwide languages 
market share’ _ the volume of support that makes 


| them the standard. For example, 
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‘All the add-ins you need | 


™@ Database access 
® SQL libraries 
™ CASE tools 


you must meet standards 


easy to understand why they attract 
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Borland C++ is the on/y popular 
compiler that meets the certified | 
ANSI C and AT&T C++ standards. 
| That means you can use essential | 
| new features like templates and 
exception handling* now. 
Whether you’re a professional 


programmer or just starting out, 
_ Borland has the innovative tools 
to get your job done fast. And with 
third-party support from companies 
like Phar Lap, Greenleaf, Inmark, 
_ KASE Works, Nu-Mega, POET, 
_ Rational, Turbo-Power, X VT, and 
Zinc, it’s smarter than ever to go | 
_ with the standard. Go with Borland | 
Pascal and Borland C++ today! 
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TURBO PASCAL Borland C++ 


~ BORLAND | nee wieraniiocs FP | 
90-day, money-back gu eg 
| See your dealer or call now, | 
| 1-800-338-6464, ext. 7075 | 


& Canada call, 1-800-461-3327 
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